API URL Structure

I make the following proposal and have implemented this in the test environment:

The URL structure should be simple and meaningful and should not be constrained by the Delivery Server URL structures. Therefore, I have implemented the following using web server rewrites. In the case of the test server, we are using IIS6 and HelconTech's ISAPI rewrite (v3) but the rules will be identical in Apache and will need minor tweaking in IIS7.

The proposed structure is:

http://<host>/api/<version>/<function>.<format> or http://<host>/api/<version>/<function>/<format>

and

http://<host>/api/<version>/<function>/<sub-function>.<format> or http://<host>/api/<version>/<function>/<sub-function>/<format>

host = server machine
version = the version of the API function.  Allows for managed deprecation and not enforcing client upgrades 
   (or breaking clients depending on function implementation)
function = the name of the function to call e.g. search
sub-function = the name of the sub function e.g. users/list - 'list' is the sub-function
format = the desired format output e.g. XML or JSON

I have implemented all the above using the following rewrite rules, which can be supplied with any distribution of the API project:

# API Rewrites
 # For version number and sub-function calls e.g. /api/1/users/list.xml /api/1/users/list/xml
RewriteRule ^/api/([0-9\.]+)/([^/]+)/([^/]+)[\.|/](xml|json)$ /cps/rde/xchg/rest/$2.$3_$4_$1.xsl/$2.$3_$1.xml?format=$4 [L,QSA]
 # For version number (recommended) e.g. /api/1/search.xml or /api/1/search/xml
RewriteRule ^/api/([0-9\.]+)/([^/]+)[\.|/](xml|json)$ /cps/rde/xchg/rest/$2_$3_$1.xsl/$2_$1.xml?format=$3 [L,QSA]

 # Fallbacks without version number
RewriteRule ^/api/([^/]+)/([^/]+)[\.|/](xml|json)$ /cps/rde/xchg/rest/$3.xsl/$1.$2.xml?format=$3 [L,QSA]
RewriteRule ^/api/([^/]+)[\.|/](xml|json)$ /cps/rde/xchg/rest/$2.xsl/$1.xml?format=$2 [L,QSA]

In my opinion, this allows for the use of a vanilla install of Delivery Server and use of features within a front-controlling Web Server that admins should have a level of comfort and understanding in anyhow i.e. not enforcing the gaining of product specific knowledge.

Let's continue the conversation on this on the Solution Exchange forum as there are other conventions and approaches that we should also discuss.

In any case, the above results in the following URL structures:

http://api.solutionexchange.info/api/1/search.xml
or
http://api.solutionexchange.info/api/1/search/xml
or
http://api.solutionexchange.info/api/1/search.json
or
http://api.solutionexchange.info/api/1/search/json

and

http://api.solutionexchange.info/api/1/users/list.xml
or
http://api.solutionexchange.info/api/1/users/list/xml
or
http://api.solutionexchange.info/api/1/users/list.json
or
http://api.solutionexchange.info/api/1/users/list/json

The 'api' path part could be removed if desired.

This all implies the following proposed conventions:

• A function file is created in Delivery Server as <function>_<version>.xml e.g. search_1.xml or users.list_1.xml

• A function format file (XSLT file) is created in Delivery Server as <function>_<format>_<version>.xsl e.g. search_json_1.xsl or users.list_xml_1.xsl

This isolates the function controller as well as the model file that defines the structure returned to the client allowing for easy modular extension of the API project.