Conventions

Content types and versioning

The developers.whispir.com 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

This implementation of an API in this manner works correctly, but conceptually it's incorrect. The issue with this design is that the request is only asking for an XML representation of some resource called a contact; it's 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 (for example, a cat or a house), and the client would need to inspect the response to determine whether it's 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.

Example:
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 doesn’t need to 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 their resource representation should be returned in. 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. It is achieved by adding a version element to the defined content types.

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

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

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

Deprecation of versions

As the version numbers grow and new features are introduced into the resource representations, it's inevitable that older versions will be deprecated and no longer supported.

This process of deprecation will be facilitated using HTTP status codes 301 and 415.

List of Whispir’s VSMTs

The following table lists the available mime types that will be accepted through Whispir’s API.

Note: The Mime Type is always singular: message-v1, not messages-v1.

Workspace

XML: application/vnd.whispir.workspace-v1+xml

xJSON: application/vnd.whispir.workspace-v1+json

Message

XML: application/vnd.whispir.message-v1+xml

xJSON: application/vnd.whispir.message-v1+json

Message Status

XML: application/vnd.whispir.messagestatus-v1+xml

xJSON: application/vnd.whispir.messagestatus-v1+json

Message Responses

XML: application/vnd.whispir.messageresponse-v1+xml

xJSON: application/vnd.whispir.messageresponse-v1+json

Message Response Rule

XML: application/vnd.whispir.responserule-v1+xml

xJSON: application/vnd.whispir.responserule-v1+json

Message Template

XML: application/vnd.whispir.template-v1+xml

xJSON: application/vnd.whispir.template-v1+json

Contact

XML: application/vnd.whispir.contact-v1+xml

xJSON: application/vnd.whispir.contact-v1+json

Distribution List

XML: application/vnd.whispir.distributionlist-v1+xml

xJSON: application/vnd.whispir.distributionlist-v1+json

Message Scenario

XML: application/vnd.whispir.scenario-v1+xml

xJSON: application/vnd.whispir.scenario-v1+json

Event

XML: application/vnd.whispir.event-v1+xml

xJSON: application/vnd.whispir.event-v1+json

Asset

XML: application/vnd.whispir.asset-v1+xml

xJSON: application/vnd.whispir.asset-v1+json

Custom List

XML: application/vnd.whispir.customlist-v1+xml

xJSON: application/vnd.whispir.customlist-v1+json

Activity Log

XML: application/vnd.whispir.activity-v1+xml

xJSON: application/vnd.whispir.activity-v1+json

User

XML: application/vnd.whispir.user-v1+xml

xJSON: application/vnd.whispir.user-v1+json

  • JSON
  • XML

Without VSMT

A Sample API request that is not using VSMT

{{codeStart}}

HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&apikey=789264

Accept: application/xml

HTTP/1.1 200 OK

Content-Type: application/xml

<contact>

<name>Neil Armstrong</name>

</contact>

{{codeEnd}}

 

With VSMT

A Sample API request that is uses VSMT

{{codeStart}}

HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&apikey=789264

Accept: application/vnd.whispir.contact+xml

HTTP/1.1 200 OK

Content-Type: application/xml

<contact>

<name>Neil Armstrong</name>

</contact>

{{codeEnd}}

 

With VSMT (including versioning)

Sample request with VSMT and Versioning (V1)

{{codeStart}}

HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&apikey=789264

Accept: application/vnd.whispir.contact-v1+xml

HTTP/1.1 200 OK

Content-Type: application/vnd.whispir.contact-v1+xml

<contact>

<name>Neil Armstrong</name>

</contact>

{{codeEnd}}

 

Sample request with VSMT and Versioning (V2)

{{codeStart}}

HTTP/1.1 GET /workspaces/123/contacts?firstName=Neil&apikey=789264

Accept: application/vnd.whispir.contact-v2+xml

HTTP/1.1 200 OK

Content-Type: application/vnd.whispir.contact-v2+xml

Neil Armstrong

+1000000000

neil.armstrong@space.com

{{codeEnd}}