3 ms·

Totally agree @hakaaak, especially with the care that should be put into making the API navigable using hyperlinks. It's kind of cool to have a browser-friendl

Totally agree @hakaaak, especially with the care that should be put into making the API navigable using hyperlinks. It's kind of cool to have a browser-friendly API to play with in the beginning, but it should be pure bonus. APIs are designed to allow a computer program to interact with another one. Favouring query strings over HTTP headers for anything other than altering the projection of a resource is non-sense. I also don't seem to understand why we must reinvent the wheel and duplicate features when HTTP clearly mentions how to specify an output format, and how to handle partial responses (Range, Content-Range, 206 Partial Response, etc). PUT is not the equivalent of "update" in CRUD. PUT is meant to replace an existing resource projection with another one. PATCH is the way to go if you want to update specific attributes of an existing resource. And what about ETags? conditional requests? It kills me when people mix pragmatism with embracing years of bad practices. That's how we end up with standards where history and legacy are more important than common sense.

w0utert 14y ago
>> I also don't seem to understand why we must reinvent the wheel and duplicate features when HTTP clearly mentions how to specify an output format, and how to handle partial responses (Range, Content-Range, 206 Partial Response, etc). It's not just individual features such as pagination and format handling where the article fails to suggest using standard HTTP features. After the first few pages -which do a pretty good job of explaining the most basic aspects of REST APIs- the document more or less switches to a 'just put it in the querystring'-attitude for about everything that goes beyond basic CRUD operations. Want a subselection of resources based on attribute values? Put the attributes in the query string. Want to limit the returned fields? Put them in the querystring. Need to non-standard logic for handling the request? Signal it in the querystring, so the API user can 'see it'. Want to query something or get a calculated response that needs input parameters (i.e. JSON-RPC)? Put all parameters in the query string. Want to suppress error codes or otherwise instruct the server to change its behaviour? Querystring... Personally I don't really like using the querystring for every bit of information you want to include in a request, because before you know it the amount of crap you can include in URLS will grow out of hand. I think dumping everything into the querystring pollutes the URI space of your API, which makes it harder to efficiently cache responses or limit access to certain API endpoints. I'm working on a web application with a REST API at the moment, and I'm trying to avoid using the querystring as much as possible. For example query arguments can also be POST-ed to a query URI that returns a link temporary resource that identifies the query result. Format specification can (and should) be handled using the Accept/Content-Type headers. Pagination can be implemented using the range and partial response headers. Complex queries that are performed often and cannot easily be encoded in a POST body (or a query string) can get their own URI (e.g. '/dogs/by-age/0-1y', '/dogs/by-age/1-5y', etc). Probably this approach has some serious downsides, but I'm still sticking with it for now. Maybe someone can make me change my mind with good arguments? ;-)
- mohamedattahri 14y ago
  You're heading the right direction. I'm one of the authors of http://greendizer.com/docs/api/ http://greendizer.com/docs/api/, and https://github.com/mohamedattahri/Nuages https://github.com/mohamedattahri/Nuages Take a look at them.

w0utert 14y ago

>> I also don't seem to understand why we must reinvent the wheel and duplicate features when HTTP clearly mentions how to specify an output format, and how to handle partial responses (Range, Content-Range, 206 Partial Response, etc). It's not just individual features such as pagination and format handling where the article fails to suggest using standard HTTP features. After the first few pages -which do a pretty good job of explaining the most basic aspects of REST APIs- the document more or less switches to a 'just put it in the querystring'-attitude for about everything that goes beyond basic CRUD operations. Want a subselection of resources based on attribute values? Put the attributes in the query string. Want to limit the returned fields? Put them in the querystring. Need to non-standard logic for handling the request? Signal it in the querystring, so the API user can 'see it'. Want to query something or get a calculated response that needs input parameters (i.e. JSON-RPC)? Put all parameters in the query string. Want to suppress error codes or otherwise instruct the server to change its behaviour? Querystring... Personally I don't really like using the querystring for every bit of information you want to include in a request, because before you know it the amount of crap you can include in URLS will grow out of hand. I think dumping everything into the querystring pollutes the URI space of your API, which makes it harder to efficiently cache responses or limit access to certain API endpoints. I'm working on a web application with a REST API at the moment, and I'm trying to avoid using the querystring as much as possible. For example query arguments can also be POST-ed to a query URI that returns a link temporary resource that identifies the query result. Format specification can (and should) be handled using the Accept/Content-Type headers. Pagination can be implemented using the range and partial response headers. Complex queries that are performed often and cannot easily be encoded in a POST body (or a query string) can get their own URI (e.g. '/dogs/by-age/0-1y', '/dogs/by-age/1-5y', etc). Probably this approach has some serious downsides, but I'm still sticking with it for now. Maybe someone can make me change my mind with good arguments? ;-)

mohamedattahri 14y ago
You're heading the right direction. I'm one of the authors of http://greendizer.com/docs/api/ http://greendizer.com/docs/api/, and https://github.com/mohamedattahri/Nuages https://github.com/mohamedattahri/Nuages Take a look at them.