Question

Just finished a first version of REST API for our enterprise application and moving on to next release. I am interested in knowing benefits / loopholes using subdomains to version the API.

Lets assume this structure:

Source folder:

   /var/www/html/domain/api/ (A)

This is the only version for now. Lets say, 2 weeks from now, we are releasing version two of API. Going to copy files from above folder to v1.0. So the new versioned folder would be;

Source folder:

   /var/www/html/domain/apiv1-0/ (B)

Folder B will be untouched. All new development will be pushed to main folder in ‘A’.
To deal with pointing the right folder, in .htaccess file, we write something like this:

  - Check the subdomain
  - Match it with the folder
  - Server files from that folder.

Example:

  api.domain.com ==> Always serves the latest version.
  apiv1-0.domain.com ==> Version 1 API will be served.
  apiv2-0.domain.com ==> Version 2 API will be served.

I want to know if this is a good practice. Any caveats?
AND
How to setup ‘.htaccess’ to take care of the above?

I don’t want to use version numbers in URI. It may be a standard practice, but I did not like it.

EDIT:
As you can see, though its different sub-domains, I do not have to worry about Apache configurations or even .htaccess configurations every time, when a new version is released.

EDIT:
The base folder:

/var/www/html/domain/

Answer 1

I want to know if this is a good practice. Any caveats?

If you mean a way of versioning and deploying your REST API, I think it’s fine. As for using htaccess routing for this, there are caveats where the different API’s could possibly be accessed through other domains, though this will depend on your server configuration more than the rules. For example, if a default vhost is setup, someone might be able to access an api folder via http://123.45.67.89/apiv1-0/.

How to setup ‘.htaccess’ to take care of the above?

You want this:

RewriteEngine On
# ensure trailing slashes for /api otherwise mod_dir will expose the underlying layout
RewriteCond %{HTTP_HOST} ^(www\.)?domain.com$ [NC]
RewriteCond %{DOCUMENT_ROOT}/api%{REQUEST_URI} -d
RewriteRule ^(.*[^/])$ /$1/ [L,R=301]

# for /api
RewriteCond %{HTTP_HOST} ^(www\.)?domain.com$ [NC]
RewriteCond %{DOCUMENT_ROOT}/api%{REQUEST_URI} -f [OR]
RewriteCond %{DOCUMENT_ROOT}/api%{REQUEST_URI} -d
RewriteRule ^(.*)$ /api/$1 [L]

# ensure trailing slashes for /apivXXX otherwise mod_dir will expose the underlying layout
RewriteCond %{HTTP_HOST} !^www\. [NC]
RewriteCond %{HTTP_HOST} ^(.+)\.domain.com$ [NC]
RewriteCond %{DOCUMENT_ROOT}/%1%{REQUEST_URI} -d
RewriteRule ^(.*[^/])$ /$1/ [L,R=301]

# for everything else
RewriteCond %{HTTP_HOST} !^www\. [NC]
RewriteCond %{HTTP_HOST} ^(.+)\.domain.com$ [NC]
RewriteCond %{DOCUMENT_ROOT}/%1%{REQUEST_URI} -f [OR]
RewriteCond %{DOCUMENT_ROOT}/%1%{REQUEST_URI} -d
RewriteRule ^(.*)$ /%1/$1 [L]

The first 2 rules are pretty much duplicated for the 2nd 2, but the first maps www* (or nothing) to /api/, and the 2nd 2 rules handle the subdomains mapped to directories (apiv1-0.domain.com maps to /apiv1-0/.

The mod_dir check is because when you try to request a directory, mod_dir’s DirectorySlash will redirect the request if there’s a missing trailing slash. When this happens, you’re layout is exposed and it will fail to work. For example, if you had a directory test under /api/, and you request http://domain.com/test, it will get rewritten to /api/test and mod_dir will see that “test” is a directory but there’s no trailing slash, so mod_dir will (incorrectly) redirect the browser to http://domain.com/api/test/, with the trailing slash but exposing the /api/.