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
