StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

POWhy would someone design a RESTful API with 'API' in the URI?
text
Body
copied!<p>I just finished reading <a href="http://rads.stackoverflow.com/amzn/click/0596529260">Restful Web Services</a> and <a href="http://blog.steveklabnik.com/2011/07/03/nobody-understands-rest-or-http.html">Nobody Understands REST or HTTP</a> and am trying to design an API with a RESTful design.</p> <p>I've noticed a few patterns in API URI design:</p> <pre><code>http://api.example.com/users http://example.com/api/users http://example.com/users </code></pre> <p>Assume that these designs properly use <code>Accept</code> and <code>Content-type</code> headers for <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html">content negotiations</a> between XHTML, JSON, or any format.</p> <blockquote> <p>Are these URI's a matter of a <em>pure</em> RESTful implementation vs implicit content negotiation?</p> </blockquote> <p>My thoughts are that by explicitly using API in the URI is so that a client will expect a data format that is not inherently human pleasing hypermedia and can be more easily consumed without explicitly setting an <code>Accept</code> header. In other words, the API is implying that you expect JSON or XML rather than XHTML.</p> <blockquote> <p>Is this a matter of separating resource representations logically on the server side?</p> </blockquote> <p>The only justification I can come up with for why someone would design their URI's with an API subdomain is because, based off my assumption that this is a scaling technique, it should make routing request load easier in a multi-tiered server infrastructure. Maybe situations exist where reverse proxies are stripping the headers? I don't know. Different servers handling different representations?</p> <p>Maybe a subdomain is used for external consumers only so that the server avoids the overhead from internal usage. Rate limiting?</p> <blockquote> <p>Am I missing a point?</p> </blockquote> <p>My proposed design would attempt to follow RESTful practices by setting appropriate headers, using HTTP verbs appropriately and representing resources in a fashion that I feel including 'API' in the URI would be redundant.</p> <blockquote> <p>Why would someone design a RESTful API with 'API' in the URI?</p> </blockquote> <p>Or could they? Maybe my problem with not understanding this design is that <em>it doesn't matter</em> as long as it follows some combination of specification which may not lead to a RESTful API implementation but close? <em>There is more than one way to skin a keyboard cat.</em> <a href="http://timelessrepo.com/haters-gonna-hateoas">HATEOAS</a> related?</p> <hr> <p><strong>Update:</strong> While researching this topic I have come to the conclusion that it's important to consider ideas from REST but not to treat it as a religion. Thus, whether or not to have 'api' in the URI is more of a design decision than a steadfast rule. If you plan to expose your website's API publicly it would be a good idea to use an api subdomain to help deal with the application's logic. I hope that someone will contribute their insight for others to learn from.</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload