Menu
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)?
916
A subdomain compartmentalizes your website so you can establish specific content types that are distinct from your root domain. On the other hand, a subdirectory is a pathway within your site. Subdirectories are a level within the domain's hierarchy.
You don't need a subdomain for your API, like api.example.com or a sub-path, like example.com/api . Your endpoint should be the root of your webpage: example.com . This is useful, because as discussed above the URL should be both the identifier as the locator of a single resource.
The subdirectory strategy concentrates your keywords onto a single domain while the subdomain strategy spreads your keywords across multiple distinct domains. In a word, the subdirectory strategy results in better root domain authority.
Subfolders are the easier site structure to set up and understand as they are the same as setting up any other folder on a website. A subfolder is similar to a subdomain in that it allows you to create categories of content, but they are set up differently on servers.
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.
102
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.
35
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
