Using the Company Workspace

Using the Company Workspace

The Company workspace is the root level workspace for all API functions.  It is a default workspace that is provided to all Whispir implementations, and can be used by application developers to quickly and easily determine all of the API functions that can be used based on their current login and access permissions.

The URL to the Company workspace is the root URL to the API; http://api.whispir.com. From here, the user is provided URLs to all other API functions and resources that they have permission to see.

Think of the Company Workspace as the URL to a website

When you browse a website, you don't have to remember all of the links to all of the pages within the site.  You simply remember the main URL and this page gives you links to the other pages that you can go to.

The Company Workspace works in the same way.  All you need to remember is api.whispir.com and based on your login details you will be provided with a list of URLs for where you can go to from here.

This means that there is no hard-coding of URLs in your application, everything can be relative to the root URL, making for far more flexible and loosely coupled applications.

How to retrieve the Company Workspace

Name

Value

Service URL

https://api.whispir.com/

Method

GET

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Accept

application/vnd.whispir.company-v1+xml
application/vnd.whispir.company-v1+json

Query String

apikey=

The Mashery API key to authenticate the request.

Response

200 OK

The request was processed successfully

401 Unauthorized

The authorization details were incorrect

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource

Request/Response

After making this request, the Company Workspace is returned as a series of URLs to each of the resources that the API user has access to. 

Each URL is stored within a 'Link' element.  Each 'Link' element that is returned contains the following information:

Element Name

Description

Method

The HTTP Method that is available on this particular URI
Rel

The searchable description about what this URI should be used for.

URI The URI in focus.  This can be used by the developer to perform some action on the resource.
Type (Optional) When the type is update or create, the applicable Content Type header and Accept header are supplied for the developer to use.

This information allows the application client to traverse the available resources easily:

HTTP 1.1 GET https://api.whispir.com/?apikey=DFD0FD90u809SDF90832FDS
Authorization: Basic asdf89234asdjg34gswr
Accept: application/vnd.whispir.company-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:company xmlns=http://schemas.api.whispir.com/dap 
             xmlns:ns2="http://schemas.api.whispir.com">
    <link method="GET" 
          rel="retrieveWorkspaces" 
          uri="http://api.whispir.com/workspaces?apikey=DFD0FD90u809SDF90832FDS"/>
    <link method="POST" 
          rel="createWorkspaces"    
          uri="http://api.whispir.com/workspaces?apikey=DFD0FD90u809SDF90832FDS" 
          type="application/vnd.whispir.workspace-v1+xml, 
                application/vnd.whispir.workspace-v1+json"/>
    <link method="GET" 
          rel="retrieveMessage" 
          uri="http://api.whispir.com/messages?apikey=DFD0FD90u809SDF90832FDS"/>
    <link method="POST" 
          rel="createMessage" 
          uri="http://api.whispir.com/messages?apikey=DFD0FD90u809SDF90832FDS" 
          type="application/vnd.whispir.message-v1+xml,
                application/vnd.whispir.message-v1+json"/>
    <link method="GET" 
          rel="retrieveContacts" 
          uri="http://api.whispir.com/contacts?apikey=DFD0FD90u809SDF90832FDS"/>
    <link method="POST" rel="createContact" 
          uri="http://api.whispir.com/contacts?apikey=DFD0FD90u809SDF90832FDS" 
          type="application/vnd.whispir.contact-v1+xml,
                application/vnd.whispir.contact-v1+json"/>
    <link method="POST" 
          rel="createUser" 
          uri="http://api.whispir.com/users?apikey=DFD0FD90u809SDF90832FDS" 
          type="application/vnd.whispir.user-v1+xml,
                application/vnd.whispir.user-v1+json"/>
    <link method="GET" 
          rel="retrieveUsers" 
          uri="http://api.whispir.com/users?apikey=DFD0FD90u809SDF90832FDS"/>
    <link method="POST" 
          rel="createTemplate" 
          uri="http://api.whispir.com/templates?apikey=DFD0FD90u809SDF90832FDS" 
          type="application/vnd.whispir.template-v1+xml,
          application/vnd.whispir.template-v1+json"/>
    <link method="GET" 
          rel="retrieveTemplates" 
          uri="http://api.whispir.com/templates?apikey=DFD0FD90u809SDF90832FDS"/>
    <link method="POST" 
          rel="createDistList" 
          uri="http://api.whispir.com/distributionlists?apikey=DFD0FD90u809SDF90832FDS" 
          type="application/vnd.whispir.distributionlist-v1+xml, 
                application/vnd.whispir.distributionlist-v1+json"/>
    <link method="GET" 
          rel="retrieveDistLists" 
          uri="http://api.whispir.com/distributionlists?apikey=DFD0FD90u809SDF90832FDS"/>
    <link method="POST" 
          rel="createScenario" 
          uri="http://api.whispir.com/scenarios?apikey=DFD0FD90u809SDF90832FDS" 
          type="application/vnd.whispir.scenario-v1+xml,
          application/vnd.whispir.scenario-v1+json"/>
    <link method="GET" 
          rel="retrieveScenarios" 
          uri="http://api.whispir.com/scenarios?apikey=DFD0FD90u809SDF90832FDS"/>
    <link method="GET" 
          rel="retrieveResponseRules" 
          uri="http://api.whispir.com/responserules?apikey=DFD0FD90u809SDF90832FDS"/>
    <link method="POST" 
          rel="createResponseRule" 
          uri="http://api.whispir.com/responserules?apikey=DFD0FD90u809SDF90832FDS" 
          type="application/vnd.whispir.responserule-v1+xml,
                application/vnd.whispir.responserule-v1+json"/>
</ns2:company>

If we take a single element of this response and break it down further, it becomes:

<link method="GET" 
          rel="retrieveWorkspaces" 
          uri="http://api.whispir.com/workspaces?apikey=DFD0FD90u809SDF90832FDS"/>

This is telling the developer that the URI
'http://api.whispir.com/workspaces?apikey=DFD0FD90u809SDF90832FDS' can be called with an HTTP GET method, and will allow the developer to 'Retrieve Workspaces'. 

Whereas, the following 'Link':

<link method="POST" 
          rel="createResponseRule" 
          uri="http://api.whispir.com/responserules?apikey=DFD0FD90u809SDF90832FDS" 
          type="application/vnd.whispir.responserule-v1+xml,
                application/vnd.whispir.responserule-v1+json"/>

This is telling the developer that the URI
'http://api.whispir.com/responserules?apikey=DFD0FD90u809SDF90832FDS' can be called with an HTTP POST method, and will allow the developer to 'Create a Response Rule'.  The Content-Type and Accept headers on the request must be set to application/vnd.whispir.responserule-v1+xml or application/vnd.whispir.responserule-v1+json.

Each 'Link' has a different use, and each developer will only be provided with 'Link' elements they have access to. 

As mentioned earlier, application developers should think of this architecture as if they were browsing a website.  In most cases, the user of the website does not have to remember all of the different URLs that they can get to for each page.  The website will advise them of these through the use of a navigation element on each page.  If the user ever got into a situation where they lost access to the navigation, they'd be lost!

We believe that APIs should be structured in the same way.  So with each response, we'll give you back all of the URLs that you can access from that location.  If you don't get any URLs back, you don't have anywhere left to go, so you can simply go back a level up the API tree.

Creating, Updating or Deleting the Company Resource

These functions are not supported in the Whispir API. 

It is likely that you are looking to use Workspaces.  Please look up the Using Workspaces documentation for more information.