[arin-tech-discuss] REST API comments

[Peter Deacon]

Thoughts on https://www.arin.net/resources/restful-interfaces.html

There are still some problems with middleware and firewalls that just will 
not accept unusual verbs (PUT,DELETE..etc)

Please consider including method overrides for PUT/DELETE in the 
documentation such as sending a variable named "method" with the requests 
or including a header... X-HTTP-Method-Override to work around these 
problems.



The practice of collapsing API application response into http status codes 
is also popular but sadly has potential to cause problems if one is not 
very careful.

Layered responses from both HTTP and the HTTP application provide the 
application with much better feedback than an HTTP layer response alone.

For example if I mess up my local URL configuration or later introduce a 
firewall or proxy change my application may end up with a 404 from 
something else (Not ARIN) entirely.  The application may then be confused 
into thinking the 404 response was actually from Arin...possibly further 
using this feedback to make incorrect assumptions about the state of 
records being managed.

Likewise on your side if your server or middleware has a problem is it 
possible for the status codes of the server or intermediate layers to ever 
overlap with the application and cause the same confusion?

If instead the application were to always depend on an application layer 
status the disambiguity and potential for problems is reduced.

Here recommend always sending ErrorPayload not just for generic status and 
recommend in documentation the application check for ErrorPayload 
preferably taking no internal action against an error response if 
ErrorPayload is not present.

~P