On Sun, Sep 29, 2013 at 1:24 PM, Renoir B. <renoirb at gmail.com> wrote: > 1. I would prefer exposing a root endpoint as a proxy that navigates for > you depending on the query parameters. > Neat advantage of this is that if your database sxhema changes, you update > the proxy and nothing else has to change. That's great in theory, but how many API-consuming applications actually operate like this? How many apps request the root and then inspect the response to understand how to make its next move? I've never seen anyone implement an API-consuming application like this, except to make a religious point. >> My take on it is that using Accept: and a custom MIME type is the "correct" >> approach for a RESTful API. But, from a practical point of view having >> everything expressed in the URL might be the way to go. Sure would make >> debugging and testing nicer w/o having to know what Accept: header was >> used. ... >> And to be clear, that version is not the overall API version, but the >> version of that specific endpoint. So, there might be in the same API >> >> PUT https://example.com/v1/account/48483/thing/1432 >> GET https://example.com/v1/account/48483/thing/1432 I don't really understand this distinction. I don't understand the use case where I would want to operate on v2 endpoints except in a couple cases where I want to use the v1 endpoint. And my brain starts to warp when I think about how you might move attributes from one endpoint in v1 into its own endpoint in v2. This just seems like an unnecessary complexity with no driving use case. That said, if internally you know that v1 and v2 of a given endpoint are exactly the same, you could route appropriately. In my opinion, you should establish unique namespaces for API versions and it should be wholesale. Here is a pragmatic, non-religious video on how to design REST APIs: http://apigee.com/about/api-best-practices/api-design-third-edition >> What about adding .json? I'm less excited about that. This seems odd: >> >> GET https://example.com/v2/account/48483/thing/1432.json This is up to you. It is not necessary and is redundant with the mime type header. -- Matt Warden http://mattwarden.com This email proudly and graciously contributes to entropy.