Versioning of REST APIs when you have multiple api under the same domain

Question

I'm designing some REST APIs which will be accessible under api.ourdomain.com/ there are going to be several APIs like

api.ourdomain.com/Provider/
api.ourdomain.com/Consumer/
api.ourdomain.com/Customer/
api.ourdomain.com/Authorization/

etc, These are not resources rather very independent APIs, out under our api sub domain.

Now the confusion I'm having is,

shall I go ahead with,

api.ourdomain.com/Provider/v1/resource/etc/

or

 api.ourdomain.com/v1/Provider/resource/etc/

So the question really is, where is it appropriate to put the version, After the name of the API

[/Provider/v1/xyz/etc]

or from Organizations perspective, v1 of api type Provider

[/v1/Provider/xyz/etc]

Any suggestion is appreciated Thanks.

Answer 1

This cannot be answered in a general manner, but I believe the answer for your case can be well determined by the intended client applications, since you are in the constrained environment and you know the business case for the API.

If your client applications need to work across "Provider" and "Consumer" sub-domains, for example, I would suggest placing the version in the API root ($SERVER/$VERSION/$SUBDOMAIN), since versioning each subdomains separately does not make much of a sense. From the client side perspective, the API acts as a single solid piece. (in the source, you have one constant "apiVersion").

If each endpoint will be used by a different client applications (for example mobile app for "Consumer" and desktop client system for the "Provider"), I suggest versioning subdomains ($SERVER/$SUBDOMAIN/$VERSION), since different development speed can be applied for various systems and the systems are more or less independent.

It is worth noting that the 2nd approach is more flexible and can be mapped to the 1st one:

$SERVER/1.0/$SUBDOMAIN_A/
$SERVER/1.0/$SUBDOMAIN_B/

can be easily rewritten as ==>

$SERVER/$SUBDOMAIN_A/1.0
$SERVER/$SUBDOMAIN_B/1.0

I would go with the second approach then, just to be a bit safer - even if you upgrade all the APIs at the same time, this will work.

A general rule to follow is to perform a good API design and do the most to avoid incompatible changes that force you to upgrade the API version.

Update: There is one more thing - the notion of API dependency. For example, if you upgrade API for authentication so that a new API version is needed, all the clients need to be upgraded too and you might need to version this API separately. This is one more point for the 2nd approach...

Hope that helps...

Answer 2

There is really no convention on this as far as I know. Here are examples of APIs from Google, Yahoo and Microsoft:

https://www.googleapis.com/language/translate/v2?parameters

http://local.yahooapis.com/MapsService/V1/geocode

http://dev.virtualearth.net/REST/v1/Locations/FR/postalCode/locality/

My preference would be to leave the version all the way at the end (like Google). This way most of the URL stays the same and only the last part is changed. Again, this would be my preference only, not convention.