5 ms·
It seems to be that many of the comments on this and other API posts recently are by people who have never had to integrate with some else's "mostly REST but on
by hartror 11y ago
It seems to be that many of the comments on this and other API posts recently are by people who have never had to integrate with some else's "mostly REST but only when it suits me" API.
If the API you are writing has these features:
* you are the consumer as well as the author.
* no other developer is ever going to need to understand it.
* don't care about server/proxy/library support.
by all means don't bother with REST.
But if you are doing one/some/all of the above implementing a HTTP REST architecture is going to make your life and fellow developer's lives easier. That is what specifications are for, there to make things easier for everyone.
The thing I find most frustrating about these discussions is REST is such a simple architecture with a well thought out technical reasoning. Yet people happily ignore parts of it because of some unstated preference, and develop their own architecture which other developers then have to divine.
- guelo 11y agoLet's say you have to integrate with my API that uses GET /user?id=1 instead of /user/1 , How have I made your life worse? Is it going to cost you any extra time at all to code it up?
- jbergens 11y agoPeople usually miss the references that should be encoded within REST responses, The hypermedia part. You should be able to call /user/ and get a list of users whith links to the specific users. This link will be in the correct http-format which means you can discover the api from one or a few starting points. This gets even more obvious when you try to fetch a sub-resource or call a "method" on a resource. Those links are encoded within the resource itself. That means when you get a user record it may contain links to things you can do with it (add an address or an extra email, get specific details etc). With SOAP it is only naming and there is very little recommendations about that.
- guelo 11y agoI guess what I object to is this concept of discoverability. No matter what, you need documentation to discover these initial endpoints, so why not document the whole API? SOAP had mechanical discover ability with WSDLs but it didn't really work. The reason REST won was because it was simple for humans to understand, which means mostly that the documentation is simple to read. As long as the URLs follow some simple consistent pattern that developers can implement without convoluted effort it should be fine, no need to follow some rigid philosophy. If the documentation is missing some key actions I doubt most developers are going to go poking around hoping to discover undocumented endpoints, they'll probably end up contacting the developer to tell them they're API is broken.
- hartror 11y agoQuerystrings for resources are technically okay in REST: > The query component contains non-hierarchical data that, along with data in the path component (Section 3.3), serves to identify a resource . . . source: https://tools.ietf.org/html/rfc3986#section-3.4 https://tools.ietf.org/html/rfc3986#section-3.4 With a caveat, you will note the "non-hierarchical data" bit. It means that this: GET /user/1/groups is valid and this: GET /user?id=1&groups is an anti-pattern. Why? The spec doesn't say of course but at a guess I'd say because there is already a hierarchical data format in URLs, the path. This assumption is build into every web framework & language I've ever used, with query strings being passed as unordered dictionaries. As you suggest the convention is to only use query strings as search parameters and the like. Personally I think conventions are useful to follow, especially when they don't cost you anything like the one we're talking about.