What are the trade-offs between different methods of constructing API URLs: subdomain vs. subdirectory and versioning?

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)?

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.

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.

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.