Good Morning,

I've been spending a lot time understanding ReST APIs and the best practices 
and recommendations for building good and useful ReST APIs.

I found that the way we handle PUT/POST requests is not correct, and could have 
very bad side effects on some ReST end-points like Requisitions.

Currently, we return a 303 (Redirect) with a Location header pointing to the 
resource that has been added or updated. On any browser, this will trigger a 
redirect following even if you don't want that. This can be true for certain 
HTTP libraries on different languages as well, when a "correct" answers is 
interpreted as "> 199 & < 300".

For this reason, we decided to fix the HTTP responses for PUT/POST/DELETE 
requests according with the ReST best practices:

* Return 201 (Created) when you add a new resource (for POST/PUT requests). In 
OpenNMS, this is not a rule for POST/PUT requests where you can either add or 
replace an existing resource. For those cases on which a POST/PUT is used for 
both operations (i.e. add/delete), we've decided to return a 204 (no content, 
because we're not returning data).

* Return 204 (no content) for all successful PUT/DELETE requests.

* Return 202 (accepted) for PUT/POST/DELETE against the Requisitions ReST end 
points. This is because all the requests will be queued to be executed 
asynchronously, so there is no way but he time a ReST request has been 
executed, if it has been successfully executed or not.

There are known side effects for returning 303 on Requisitions that impact very 
badly the new Requisitions UI, and even third party integrations, if you follow 
the redirects. In case of the UI, there is no way to avoid following redirects.

I would like to know how you're currently using the ReST API of OpenNMS, to 
understand how this could impact your current integration. I have to say, that 
in theory this should not impact your integration. If should make it better, 
because we will return the correct HTTP code.

Even knowing that this is kind of a bug fix, this can also be seen as an API 
change. For this reason, we're going to release Horizon 18 just because of this 
change (i.e. 17.1.0, plus the all fixed introduced after this version, plus the 
ReST API change), and all the features promised for 18 will be on 19 (without 
altering the schedule, we're just renumbering the versions to be clear with the 
fact that we're changing an API). That also means, Meridian 2016 will be based 
on 18, and so on.

I would appreciate any comments, concerns, thoughts or use cases you have about 
this topic.

Regards,
Alejandro.
------------------------------------------------------------------------------
Site24x7 APM Insight: Get Deep Visibility into Application Performance
APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
Monitor end-to-end web transactions and take corrective actions now
Troubleshoot faster and improve end-user experience. Signup Now!
http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
_______________________________________________
Please read the OpenNMS Mailing List FAQ:
http://www.opennms.org/index.php/Mailing_List_FAQ

opennms-devel mailing list

To *unsubscribe* or change your subscription options, see the bottom of this 
page:
https://lists.sourceforge.net/lists/listinfo/opennms-devel

Reply via email to