69

We have a web application with a domain name of example.com. Now we want to extend a part of this application as a REST API, and we are debating on the best URL pattern.

We could use the URL pattern api.example.com or example.com/api. What trade-offs are there to consider, if any?

Additionally, what trade-offs are there regarding methods of API versioning? It could be done via the URL (v1.api.example.com, example.com/api/v1, or some strange mix v1.example.com/api or api.example.com/v1). Alternatively, it could be done through the use of HTTP request headers (or otherwise)?

Ders
  • 1,068
  • 13
  • 16
Abhijith Prabhakar
  • 1,325
  • 3
  • 12
  • 24
  • Is there any prior experience at any other company assets, or anywhere else in the development team? Either choice would work just fine. – Andrew Jan 28 '13 at 03:15
  • 5
    Both looks fine, In one of our project we opted for `api.XXXXX.com` format – Arun P Johny Jan 28 '13 at 03:20
  • Even, we had the same discussion at work, we went with api.xxxx.com. This approach seemed neater. We have different set up for the API Cluster now. – Srinivas Jan 28 '13 at 03:36
  • 5
    There is one major difference - api.example.com would add CORS requests, whereas example.com/api won't. – aarjithn Jul 01 '19 at 06:50
  • yes, api.example.com adds CORS, does it become performance bottleneck is the question ? – codeaprendiz Apr 13 '22 at 15:12

3 Answers3

23

It depends on your needs.

If you use http://api.example.com it makes your API a subdomain. Basically, this URL pattern is good if your REST service is to be consumed by multiple clients, but if only one client is connected to your API then the pattern http://example.com/api/v1 is good. However, if you want to add more API with more clients connected to it it’s better to use http://example.com/api/v1. For example, consider the following.

http://example.com/reportapi/apioperation?parameters

http://example.com/paymentapi/apioperation?parameters

http://example.com/searchapi/apioperation?parameters

Last but not least, PayPal uses the pattern http://example.com/api/v1.

TRiG
  • 10,148
  • 7
  • 57
  • 107
Jobert Enamno
  • 4,403
  • 8
  • 41
  • 63
5

I think you should consider using neither http://api.example.com nor http://example.com/api/v1.

Instead I would suggest using http://example.com/api and content negotiation for versioning.

Here are my thoughts why:

Using a subdomain:

Per the URI Scheme Specification, you are defining the API in the authority part of the URI, which is used to define your host, rather than defining an application or API on your host. You are actually creating a different address for your API, which means that authentication might not work for api.example.com as it does for example.com.

A valid reason to do this might be when designing an new instance for mobile devices, e.g. mobile.example.com, but I would consider this more an infrastructural decision and not a functional one.

Using an unversioned path on the main domain:

There are two bits of information here: one is an indication that there is an API resource and the second is that there the version number of that API resource (v1).

There is nothing bad about using /api/ to put a distinction between the API and, for example, your web view that might run under /web/. This can be considered common best practice.

I am not sure whether you intended this, but your question includes a query on how to solve API versioning. Personally, I think that API versioning should not be done using URLs, as they are intended to stay stable for as long as possible. Cool URIs don't change! Instead, consider using HTTP Content-Type information to version your API. I actually found this method used in VMware documentation. Additionally here is a quite old, but still useful, post about content type versioning by Peter Williams.

Community
  • 1
  • 1
brazo
  • 704
  • 4
  • 11
  • 15
    I feel like having the version in the url is follows the "Cool URIs don't change" way better than using Content-Type for the version. Why? Let's say you change the name of your users model to person in a future release, so you just redirect users to people. Then, at a later point, you decide to add a new model named users. Now, you are forced to change the url. Instead, you could have used versioning in the url from the start. 100 releases later, if you keep your v1 api working, then all of the v1 links will work exactly the same. Simple. (plus urls are mostly easier to change then headers) – Ben Aubin Aug 17 '16 at 23:33
  • 9
    I *definitely* don't agree with this answer. Ben's comment kind of gets at it, but it's not very clear. The important takeaway is that when someone bases their application's functionality on your API, they need some guarantee that your API is always going to accept what they're giving it and return what they're expecting from it. If you don't version your URLs, then a given URL will inevitably start to drift as your internal implementation matures and changes. – kael Jul 25 '17 at 18:57
  • 4
    Disagree 100%. Authentication could work on all subdomains if need, but anyway, you generally don't want the same auth for your API (eg. API keys). Moreover, the HTTP Content-Type solution is needlessly overcomplicated, and different versions of the API will probably not be using the same urls. You'll end up in shared urls, and some specific others... perfect mess :/ – Profet Aug 06 '18 at 00:10
  • I think all of these answers are both right and wrong on some things. First, we can definitely handle cross-domain authentication and authorization nowadays. While I sympathize with the views of Ben, Kael, and Profet I would challenge them to think about what a URI is. A URI isn't _merely_ the string in the URL bar or target of your request. It's also metadata. Metadata such as which representation of the underlying resource you want. Keep in mind that URIs are not _the resource itself_, they are an identifier than can point to different representations. – jamesconant May 30 '20 at 15:12
  • (continued) Further, declaring which representation you want to request could be done _either_ by adding more information to the URL string _or_ by using content-negotiation. Strictly speaking, just having `/api/v1/posts` doesn't mean you are always getting the _exact_ same representation of posts, as their could have been minor and patch version updates that just weren't breaking. I think this is one of those cases where it seems easier to have an obvious (url versioning), but if we stretch our minds a little bit we realize it's not that different from putting that same data somewhere else. – jamesconant May 30 '20 at 15:16
0

This is a case of tradeoffs, with no single best solution.

For example, if your http://example.com/ provides content through a standard web interface as well as through the API, then you need something like http://api.example.com/api/<version>/<the usual resource pattern> just to separate browser-based application access from API interaction. Does this make sense?

Example: api.rottentomatoes.com

However, even if your domain is dedicated for API calls, it’s meaningful to use the above pattern anyway, and reserve http://example.com/ for other ways of interacting with your application. For example, you might want http://example.com/mobile/, etc.

Jeff Widman
  • 22,014
  • 12
  • 72
  • 88
TheWhiteRabbit
  • 15,480
  • 4
  • 33
  • 57