Using Workspaces

Using Workspaces

Using Workspaces, application developers are able to create new work areas for the varying use cases of each application. 

Each of these work areas provides different functions and capabilities that can be provided to users of the application, e.g. creating messages, executing scenarios, or viewing distribution lists.

The following details describe how application developers can use the Workspaces through Whispir’s API.

  1. How to retrieve a list of Workspaces
  2. How to retrieve a single Workspace
  3. How to create new Workspaces
  4. How to update an existing Workspace
  5. How to delete an existing Workspace

How to retrieve a list of Workspaces

Name

Value

Service URL

https://api.whispir.com/workspaces?apikey=

Method

GET

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Accept

application/vnd.whispir.workspace-v1+xml
application/vnd.whispir.workspace-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 Example

After performing this request, the response contains a list of URLs to each of the Workspaces 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:

HTTP1.1 GET https://api.whispir.com/workspaces?apikey=DFD0FD90u809SDF90832FDS
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Accept: application/vnd.whispir.workspace-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
    <status>1 to 1 of 1</status>
    <ns2:workspaces>
        <ns2:workspace>
            <projectName>Community Recovery</projectName>
            <projectNumber></projectNumber>
            <status>A</status>
            <billingcostcentre></billingcostcentre>
            <ns2:link method="GET" 
                      rel="self" 
                      uri="https://api.whispir.com/workspaces/A4F978D7485B73A2?apikey=DFD0FD90u809SDF90832FDS"/>
        </ns2:workspace>
    </ns2:workspaces>
</ns2:return>

The elements returned in the response are described as follows:

Element Name

Description

projectName

The name of the Workspace.
projectNumber

The ID of the workspace.

status

The status of the Workspace:
A: Active
D: Disabled (not available to be used or accessed) 

billingcostcentre Only applicable to customers with the Billing Cost Centre Module enabled. Shows the billing cost centre set for the Workspace.
link The URL for the user/application to access this specific workspace.

How to retrieve a single Workspace

Name

Value

Service URL

https://api.whispir.com/workspaces/:id?apikey=

Method

GET

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Accept

application/vnd.whispir.workspace-v1+xml
application/vnd.whispir.workspace-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

404 Not Found

The requested resource specified by the ID in the URL was not found, most likely this ID does not exist or has been deleted

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource

Request/Response Example

The response returns the specific details of the Workspace that the API user requested.  

HTTP 1.1 GET https://api.whispir.com/workspaces/CFEF25E421A69BC4?apikey=<your api key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Accept: application/vnd.whispir.workspace-v1+xml 

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

This response shows all of the available functions that the user can perform from within this Workspace.  Think of this response as the website navigation.  Each URL returned allows the user to perform a different function, as in visit a different web page.

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

Function

Rel

URI

Method

Retrieve a listing of messages

retrieveMessage http://api.whispir.com/workspaces/[id]/messages GET
Create a new Message createMessage

http://api.whispir.com/workspaces/[id]/messages

POST

Retrieve a listing of contacts retrieveContacts http://api.whispir.com/workspaces/[id]/contacts GET
Create a new contact createContact http://api.whispir.com/workspaces/[id]/contacts POST
Retrieve a listing of users retrieveUsers http://api.whispir.com/workspaces/[id]/users GET
Create a new user createUser http://api.whispir.com/workspaces/[id]/users POST
Retrieve a listing of message templates retrieveTemplates http://api.whispir.com/workspaces/[id]/templates GET
Create a new message template createTemplate http://api.whispir.com/workspaces/[id]/templates POST
Retrieve a listing of distribution lists retrieveDistLists http://api.whispir.com/workspaces/[id]/distributionlists GET
Create a new distribution list createDistList http://api.whispir.com/workspaces/[id]/distributionlists POST
Retrieve a listing of scenarios retrieveScenarios http://api.whispir.com/workspaces/[id]/scenarios GET
Create a new scenario createScenario http://api.whispir.com/workspaces/[id]/scenarios POST
Retrieve a listing of Response Rules retrieveResponseRules http://api.whispir.com/workspaces/[id]/responserules GET
Create a new Response Rule createResponseRule http://api.whispir.com/workspaces/[id]/responserules POST

Each of these URIs can be accessed using the REL and appropriate METHOD to perform the specified functionality.

How to create a new Workspace

Name

Value

Service URL

https://api.whispir.com/workspaces/?apikey=

Method

POST

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Accept

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

Content-Type

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

Query String

apikey=

The Mashery API key to authenticate the request.

Response

202 Accepted

The request has been accepted for processing

401 Unauthorized

The authorization details were incorrect

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource

Request/Response Example

The example below shows the Workspace that the API user is requesting to have created in the Whispir Platform.  

There is no limit to the amount of workspaces each API user can create.

HTTP 1.1 POST https://api.whispir.com/workspaces?apikey=
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Accept: application/vnd.whispir.workspace-v1+xml 
Content-Type: application/vnd.whispir.workspace-v1+xml 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:workspace xmlns:ns2=http://schemas.api.whispir.com/dap  
               xmlns:ns3="http://schemas.api.whispir.com">
    <projectName>Sandbox 3</projectName>
    <projectNumber></projectNumber>
    <status>A</status>
    <billingcostcentre></billingcostcentre>
</ns3:workspace>

The elements required in the request are described as follows:

Element Name

Description

projectName (mandatory)

The name of the Workspace to be created.
projectNumber (optional)

The ID of the workspace, generally not used.

status (mandatory) The status of the Workspace being created.  This should be 'A' for 'Active' when creating new workspaces.
billingcostcentre (optional) Only applicable to customers with the Billing Cost Centre Module enabled. Allows the user to set a billing cost centre for the Workspace.

How to update an existing Workspace

This is useful if you are wanting to change the name of a workspace, or update some detail e.g. Workspace ID (projectNumber).

Name

Value

Service URL

https://api.whispir.com/workspaces/CFEF25E421A69BC4?apikey=

Method

PUT

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Accept

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

Content-Type

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

Query String

apikey=

The Mashery API key to authenticate the request.

Response

204 No Content

The request has been processed and no content was returned.  This is a successful update.

401 Unauthorized

The authorization details were incorrect

404 Not Found

The resource specified in the URI could not be updated because it could not be found.

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource

Request/Response Example

The example XML shows the Workspace that the API user is requesting to have updated.  

Note that the URL that is being specified in the request is locating a specific Workspace with the ID: CFEF25E421A69BC4. This is telling the API, here is the Workspace that I want to update, and here is the information that I want to update it with.

HTTP 1.1 PUT https://api.whispir.com/workspaces/CFEF25E421A69BC4?apikey=
Authorization: Basic asdf98nf89asdvasd2r398h8sdf
Accept: application/vnd.whispir.workspace-v1+xml 
Content-Type: application/vnd.whispir.workspace-v1+xml 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns3:workspace xmlns:ns2=http://schemas.api.whispir.com/dap  
               xmlns:ns3="http://schemas.api.whispir.com">
    <projectName>Sandbox 3</projectName>
    <projectNumber></projectNumber>
    <status>A</status>
    <billingcostcentre></billingcostcentre>
</ns3:workspace>

The elements required in the request are described as follows:

Element Name

Description

projectName (mandatory)

The name of the Workspace to be created.
projectNumber (optional)

The ID of the workspace, generally not used.

status (mandatory) The status of the Workspace being created.  This should be 'A' for 'Active' when creating new workspaces.
billingcostcentre (optional) Only applicable to customers with the Billing Cost Centre Module enabled. Allows the user to set a billing cost centre for the Workspace.

When using PUT it is important to remember that it is a replacement of the existing information.  All information supplied in the body of the request will be used to replace the existing information.  If you leave a field blank, it will remove the existing information.

Note: Performing a PUT on the Workspace does not modify any of the contents of the Workspace e.g. Templates or Distribution Lists.  This operation only modifies the details of the actual Workspace.

How to delete an existing Workspace

Please be very careful when deleting Workspaces as this operation is irreversable.

Name

Value

Service URL

https://api.whispir.com/workspaces/CFEF25E421A69BC4?apikey=

Method

DELETE

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

Query String

apikey=

The Mashery API key to authenticate the request.

Response

204 No Content

The DELETE request has been accepted for processing

401 Unauthorized

The authorization details were incorrect

404 Not Found

The workspace ID specified in the URI could not be deleted because it does not exist.

Request/Response Example

The example XML shows the Workspace that the API user is requesting to be deleted 

HTTP 1.1 DELETE https://api.whispir.com/workspaces/CFEF25E421A69BC4?apikey=<your api key>
Authorization: Basic asdf98nf89asdvasd2r398h8sdf

The DELETE request does not require any information to be supplied in the body, it is simply sending a DELETE to a URL.  

Whispir will immediately delete all of the information within this Workspace, and this operation is irreversable (aside from restoring from backups which may result in support costs).

If you require more information about deleting Workspaces, please contact apisupport@whispir.com. or post a message in the forum.

Value

Service URL

https://api.whispir.com/workspaces/

Method

GET

Request Headers

Authorization

The Base 64 representation of the Whispir Username and Password.

 

Accept

application/vnd.whispir.workspace-v1+xml

application/vnd.whispir.workspace-v1+json

 

Query String

apikey=

The Mashery API key to authenticate the request.

limit=

The number of results to return in the query

offset=

The number from the first result to start returning records

name=

The Name of the workspace to return

description=

The description of the workspace to return

Response

200 OK

The request was processed successfully

401 Unauthorized

The authorization details were incorrect

404 Not Found

The requested resource was not found

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource