3 ms·

Let'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 tim

by guelo 12y ago

Let'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 12y ago
People 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 12y ago
  I 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 12y ago
Querystrings 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.

by guelo 12y ago

Let'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 12y ago

People 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 12y ago
I 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 12y ago

Querystrings 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.