API Architecture

Architectural Overview

Whispir's API provides interfaces for application clients to utilise Whispir functionality that are platform agnostic, without any dependency on the environment or programming language being used.

Whispir's API supports multiple methods of inbound request over HTTPS, primarily:

  • XML
  • JSON

Clients can issue requests using either of the methods, and receive a response in the same format.  This allows easy integration with existing and new applications using technologies that are widely supported in a range of languages.

Whispir's RESTful Architecture

Whispir’s API employs a ‘REST’ (Representational State Transfer) architecture.  This architecture is the foundation of the World Wide Web and is widely used in application, service and API development.

An application is considered ‘RESTful’ if it conforms to a ‘REST’ architecture.  A ‘REST’ architecture consists of clients and servers.  The clients initiate requests to the servers, and the servers process the requests and return the appropriate responses.  Requests and responses are structured using defined and addressable resources

Each resource within the Whispir API is available through a secure and authenticated URI. 

Retrieving a list of resources

Application clients can retrieve a list of resources of a single type through a simple URI. 

For example, to retrieve a list of Workspaces from within the Company, the URI is as follows:

//Retrieve all workspaces within your Company

HTTP 1.1 GET http://api.whispir.com/workspaces?apikey=bneov3023nfo023rssdf3

Or, to retrieve a list of Messages from within the Company, the URI is as follows:

//Retrieve all messages within your Company

HTTP 1.1 GET http://api.whispir.com/messages?apikey=bneov3023nfo023rssdf3

Retrieving a single resource

Application clients also have access to a single resource by specifying the relevant ID of the resource.  This information would have been returned when retrieving the list of resources as specified above.

To retrieve a single Workspace when you know the ID, the URI is as follows:

//Retrieve the Workspace with the ID of 12345

HTTP 1.1 GET http://api.whispir.com/workspaces/12345?apikey=bneov3023nfo023rssdf3

Or to retrieve a single Contact when you know the ID, the URI is as follows:

//Retrieve the Contact with the ID of 78910

HTTP 1.1 GET http://api.whispir.com/contacts/78910?apikey=bneov3023nfo023rssdf3

Nested resource requests

Within Whispir's resource model, some resources are nested within one another.  For example, the Company resource contains many Workspaces.  The Workspace resource contains many Messages
Each Message resource contains a MessageStatus.

Requests can be "chained" or "nested" in order to provide application clients the ability to access specific resources when they are nested.

For example, if you wanted to retrieve a Contact from within a Workspace, the URI would look as follows:

//Retrieve the Contact with the ID 67890 from within the Workspace with ID 12345

HTTP 1.1 GET http://api.whispir.com/workspaces/12345/contacts/67890?apikey=bneov3023nfo023rssdf3

Note: More information about REST can be found on Wikipedia.

HTTP Response Codes

Application clients that are using Whispir's API will receive HTTP response codes in response to every request that is issued. 

The table below describes the response codes that will be issued and gives potential reasons as to why they may have been sent back.

Response Code

Description

Actions for application client

Successful Response Codes

200 OK

Successful request

No action required

201 Created

Successfully created the resource.

The requested resource has been successfully created and can be found via the URI in the ‘Location’ header

202 Accepted

Successfully accepted the request for processing

The request has been accepted for processing by the asynchronous processor.

204 No Content

Successfully processed the request, but no content was sent back

The update (PUT) or delete (DELETE) request has been successfully processed, and no content was returned from the server.

301 Moved Permanently

Successful request, but the resource is no longer available at this location.

This resource URI should no longer be used. Check the location header of the response and redirect the request there.

302 Found

Successful request, but the resource is temporarily not available at this location.

This resource URI should still be used in future, but for this specific request, check the location header of the response and redirect the request there.

304 Not modified

Content hasn’t changed since last request

No action required

Unsuccessful Response Codes

400 Bad Request

Invalid or missing request parameters

Inspect the request parameters and ensure that all required parameters are supplied.

Note the error text in the response and update the request accordingly

401 Unauthorized

Invalid or no credentials passed in the request

Inspect the authorisation header and ensure that a valid authentication has been provided

403 Forbidden

Authorization credentials passed and accepted but account does not have permission

Inspect the authorisation header and ensure that a valid authentication has been provided

404 Not Found

The requested URI does not exist

The requested resource was not found, inspect the ID in the URI that was used and ensure that it is valid

405 Method not allowed

The requested resource does not support the supplied verb

Inspect the HTTP method that was used in the request and ensure that it is valid for the resource being requested

415 Unsupported Media Type

The request was unsuccessful because the requested content type is not supported by the API.

The application client can use this response to determine if it is asking for a supported version of a resource.  Upon receiving this response, the client can query Mashery developer documentation to determine the appropriate version for the requested resource.

422 Unprocessable Entity

The request is formed correctly, but due to some condition the request cannot be processed e.g. email is required and it is not provided in the request

The request did not contain all of the information required to perform this method.  Please check your request for the required fields to be passed in and try again.  The offending fields will be specified in the error text of the response.

Alternatively, consult the Mashery documentation, or contact your administrator or apisupport@whispir.com for more information.

500 Internal Server Error

An internal error occurred when processing the request.

Attempt the request again and if the HTTP 500 error re-occurs contact apisupport@whispir.com

501 Method Not Implemented

The HTTP method being used has not yet been implemented for the requested resource

The method being used is not implemented for this resource.  Please check the documentation, or contact the administrator. 

Alternatively, contact apisupport@whispir.com.

503 Service Unavailable

The service requested is currently unavailable.

Attempt the request again and if the HTTP 503 error re-occurs contact apisupport@whispir.com