High five for the Heroku API designer who decided to use the Accept header to indicate the acceptable format and version of the response. This is the way to design HTTP APIs.
Instead, most companies put the version number in the URL and use special suffixes on the URL like ".json" to indicate these things. I can understand this practice from the standpoint of convenience. A human using cURL can't be bothered to type out an Accept header. But when building an API support should first be considered for explicit, programmatic API clients, not humans. Then you can slap on your human-friendly URL extensions, etc.
Thanks, glad you like it. A ton of thought went into a lot of the little choices like that. We plan to dig more into how and why those choices were made as we move forward.
This will be very interesting for those of us looking to learn more about building APIs. I for one am definitely looking forward to future posts on the subject!
Great, do let me know if there are particular questions you have and we can be sure to cover them. Otherwise I hope to start covering the key things that I think are interesting or important in the not too distant future.
Thanks for sharing the link. There definitely can be a lot of gotchas and things that are easy to overlook until you see a good talk or are right in the middle of it.
I might be misinformed, but wasn't the purpose of stuffing version/format into the URL so that it is easier to develop with? I.e. setting only one URL to make a request is easier than having to set an URL + Accept Version Header + Accept Format Header.
Both the format and version are in the same header if that helps. So there are a couple values in there you might have to change, similar to the couple values you would have to change in the url to modify version/format. So in that regard I think the difficulty or complexity of one or the other is pretty similar. Hope that helps explain a bit, but let me know if I missed the point of your question.
Comments
High five for the Heroku API designer who decided to use the Accept header to indicate the acceptable format and version of the response. This is the way to design HTTP APIs.
Instead, most companies put the version number in the URL and use special suffixes on the URL like ".json" to indicate these things. I can understand this practice from the standpoint of convenience. A human using cURL can't be bothered to type out an Accept header. But when building an API support should first be considered for explicit, programmatic API clients, not humans. Then you can slap on your human-friendly URL extensions, etc.
It's always easier to start out being explicit.
Thanks, glad you like it. A ton of thought went into a lot of the little choices like that. We plan to dig more into how and why those choices were made as we move forward.
This will be very interesting for those of us looking to learn more about building APIs. I for one am definitely looking forward to future posts on the subject!
Great, do let me know if there are particular questions you have and we can be sure to cover them. Otherwise I hope to start covering the key things that I think are interesting or important in the not too distant future.
+1. I did not appreciate these concepts until I watched Designing a Beautiful REST+JSON API http://youtu.be/5WXYw4J4QOU
Thanks for sharing the link. There definitely can be a lot of gotchas and things that are easy to overlook until you see a good talk or are right in the middle of it.
I might be misinformed, but wasn't the purpose of stuffing version/format into the URL so that it is easier to develop with? I.e. setting only one URL to make a request is easier than having to set an URL + Accept Version Header + Accept Format Header.
Both the format and version are in the same header if that helps. So there are a couple values in there you might have to change, similar to the couple values you would have to change in the url to modify version/format. So in that regard I think the difficulty or complexity of one or the other is pretty similar. Hope that helps explain a bit, but let me know if I missed the point of your question.