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

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:

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:

How to retrieve a single Workspace

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:

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

How to create a new Workspace

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:

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).

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:

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.

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.