Content Types & Versioning

Content Types & Versioning

Whispir's API has been designed and built to support the wide feature set provided in the current version of the Whispir Platform. 

In order to manage and incorporate change in future versions of the API, Whispir's API has implemented a versioning structure that allows application clients to choose which version of the API they would like to retrieve their responses from.

This allows new versions to be built and old versions to be supported concurrently, with no impact to clients when changes are made.

Whispir's API achieves this versioning capability by using Vendor Specific MIME Types (VSMT).

Without VSMT

If the implementation was not using VSMT, the request and response would look as follows:

=== REQUEST ===>
HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&apikey=789264 
Accept: application/xml

<== RESPONSE ===
HTTP/1.1 200 OK
Content-Type: application/xml
<contact>
   <name>Neil Armstrong</name>
</contact>

This implementation of an API in this manner works correctly, but conceptually it is incorrect.  The issue with this design is the request is only asking for an XML representation of some resource called a Contact, it is not specifically asking for the XML version of a Contact Resource as defined by Whispir's API.

Any XML representation of a resource could be passed back e.g. a Cat or a House, and the client would need to inspect the response to determine whether it is a Contact or not through its own means.

With VSMT

By using VSMT, Whispir can define and make available the various content types for resources prior to the requests being made. This allows the application clients to specify the resource that they would like to receive from the API, and Whispir will only return content of that specific type.

For example:

=== REQUEST ===>
HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&accessID=789264
Accept: application/vnd.whispir.contact+xml

<== RESPONSE ===
HTTP/1.1 200 OK
Content-Type: application/vnd.whispir.contact+xml
<contact>
   <name>Neil Armstrong</name>
</contact>

By using this method, the client is specifically asking for a resource representation of a Contact that is defined by Whispir's API.  There is no confusion about the representation that will be returned, and the client need not worry about validation as Whispir will only ever return a valid Contact as a response to this request.

VSMT also allows the client the ability to choose the language in which their resource representation should be returned.  Using the previous example, the application client was asking for the Contact to be returned in XML.

Accept: application/vnd.whispir.contact+xml

This Contact resource could just as easily be returned as a JSON object by changing the content type as follows:

Accept: application/vnd.whispir.contact+json

With VSMT (including versioning)

This method of using VSMT also allows the resource representations to be updated, re-written and maintained without any notification required to application clients.

This can be achieved by adding a version element to the defined content types.  This is demonstrated below:

=== REQUEST ===>
HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&accessID=789264 
Accept: application/vnd.whispir.contact-v1+xml

<== RESPONSE ===
HTTP/1.1 200 OK
Content-Type: application/vnd.whispir.contact-v1+xml
<contact>
   <name>Neil Armstrong</name>
</contact>

By versioning the application MIME types, application clients can request the resource representation that their application is built on, e.g. ‘contact-v1’, or ‘workspace-v2’.

Whispir can create new representations of these documents, and the application clients will not be affected by these changes.

E.g. if a Contact was to be updated to contain more elements, it could look as follows:

=== REQUEST ===>
HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&accessID=789264 
Accept: application/vnd.whispir.contact-v2+xml

<== RESPONSE ===
HTTP/1.1 200 OK
Content-Type: application/vnd.whispir.contact-v2+xml
<contact>
   <name>Neil Armstrong</name>
   <mobile>+61456838435</mobile>
   <email>neil.armstrong@space.com</email>
</contact>

The v2 version of this resource representation can co-exist with the v1 version, and application clients do not need to worry about their existence.

Deprecation of Versions

As the version numbers grow and new features are introduced into the resource representations, it is inevitable that the older versions will become deprecated and no longer supported over an extended period of time.

This process of deprecation will be facilitated using HTTP Status Codes 301 and 415.

List of Whispir's VSMT's

The following table depicts the available mime types that will be accepted through Whispir's API:

Resource Type

XML Mime Type

JSON Mime Type

Workspace

application/vnd.whispir.workspace-v1+xml

application/vnd.whispir.workspace-v1+json

User

application/vnd.whispir.user-v1+xml

application/vnd.whispir.user-v1+json

Permission

application/vnd.whispir.permission-v1+xml

application/vnd.whispir.permission-v1+json

Message

application/vnd.whispir.message-v1+xml

application/vnd.whispir.message-v1+json

Message Status

application/vnd.whispir.messagestatus-v1+xml

application/vnd.whispir.messagestatus-v1+json

Contact

application/vnd.whispir.contact-v1+xml

application/vnd.whispir.contact-v1+json

Template

application/vnd.whispir.messagetemplate-v1+xml

application/vnd.whispir.messagetemplate-v1+json

Distribution List

application/vnd.whispir.distributionlist-v1+xml

application/vnd.whispir.distributionlist-v1+json

Response Rule

application/vnd.whispir.responserule-v1+xml

application/vnd.whispir.responserule-v1+json

Event Type

application/vnd.whispir.eventtype-v1+xml

application/vnd.whispir.eventtype-v1+json

Event

application/vnd.whispir.event-v1+xml

application/vnd.whispir.event-v1+json

Report

application/vnd.whispir.report-v1+xml

application/vnd.whispir.report-v1+json