Why would someone design a RESTful API with 'API' in the URI?

Question

I just finished reading Restful Web Services and Nobody Understands REST or HTTP and am trying to design an API with a RESTful design.

I've noticed a few patterns in API URI design:

http://api.example.com/users
http://example.com/api/users
http://example.com/users

Assume that these designs properly use Accept and Content-type headers for content negotiations between XHTML, JSON, or any format.

Are these URI's a matter of a pure RESTful implementation vs implicit content negotiation?

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 Accept header. In other words, the API is implying that you expect JSON or XML rather than XHTML.

Is this a matter of separating resource representations logically on the server side?

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?

Maybe a subdomain is used for external consumers only so that the server avoids the overhead from internal usage. Rate limiting?

Am I missing a point?

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.

Why would someone design a RESTful API with 'API' in the URI?

Or could they? Maybe my problem with not understanding this design is that it doesn't matter as long as it follows some combination of specification which may not lead to a RESTful API implementation but close? There is more than one way to skin a keyboard cat. HATEOAS related?

---

Update: 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.

Answer 1

I would (and have) done it to separate it from the 'website' infrastructure because it's probably going to have a higher load and require more infrastructure - it's a lot easier to do millions of API calls a day than get that in page views because you have the full load of n sites/companies and their efforts and traction, collectively and even in some cases individually they're going to attract more traffic than you yourself.

Answer 2

Also keep in mind, that most frameworks (django, RoR,...) provide URL-based routing out of the box. You probably need different views for API vs. HTML responses to manage things like authentication, trotting, limits-check and other specific stuff differently.

Putting in place an additional HTTP-Header based routing system to allow, as you say, implicit content negotiation is often not worth the effort.

Answer 3

This is my understanding and point of view about your question :

Are these URI's a matter of a pure RESTful implementation vs implicit content negotiation?

No, they are not part of any official documentation (that I know of), and are usually at the developper/team standards discretion. For example, Zend Framework uses some utility classes to detect XHR requests and how responses should be returned. Granted, ZF is not pure RESTful design (or most PHP application as a matter of fact), but it is still possible to write such designs even in PHP.

I have often seen api being used in urls when the returned data expected is indeed not meant to be used as is for display to the end user. However it is usually a design decision and not necessarily an implied standard.

Is this a matter of separating resource representations logically on the server side?

More or less. For example, when performing a PUT request, for example, the interface does not necessarily need to be entirely refreshed, and often a simple response message is good enough. While this response message is part of the view, it is not the view. So, for example, http://domay.com/users/ would return the interface to manage users (or whatever), http://domain.com/users/api would perform operations and return interface updates (without a page reload).

Am I missing a point?

Weell, no. Since it is a design decision to use or not api in the URL, you're not missing anything here. With the proper headers,

http://domain.com/users/api/get
http://domain.com/users/get
http://domain.com/users/

can all be valid RESTful requests.

Why would someone design a RESTful API with 'API' in the URI?

Simply put, to have an URL naming convention. So that, when looking at a request in logs, documentation, etc. One will understand it's purpose.

Answer 4

User-visible webpage URLs are subject to the whims of webmasters, designers, corporate organization, marketing, fashion, technology, etc.

An API, on the other hand, is supposed to remain stable. By using a subdomain you isolate your API from the rest of the website and the changes it is likely to undergo in time.