Getting Started

Conventions used

Bold - Mostly hyperlinks or just plain text for highlighting the current API page. Eg. in Tenant page there is no need to make link to itself it is just bold text.

Italic - Indicates highlighted words or meanings.

id - Indicates the code properties and assigned values like true or null.

Hint

Indicates some text that is a note to give more information on some subject.

Warning

Indicate some text that warns of something that can happen and will not result in error.

Danger

Indicate some text that will cause some errors and developers should be aware of its implication(s).

Coach

The Coach has two main parts:

  • Console the administrative part where the Tenant hierarchy can be created, connection to Recorder(s) and assign different Media Players for playback, and set Scheduled Tasks.
  • QM or Quality Monitoring part for media file monitoring standards to be established and then used to analytically evaluate files with the inclusion of carefully targeted coaching tools.

Note

This REST API is fully implemented for administrative part of Coach or Console part. There are few settings that can be set for QM but they are all assigned through Console API.

Formats

Currently supported format are JSON (JavaScript Object Notation) and XML. Requests are valid as long as they are sent as HTTP Header Content-Type application/json or application/xml, and result response format is same as sent request format.

Authentication

With installation of Coach each customer will be provided with unique API Key and API Secret. The API Key and Secret are need for authentication to the Coach REST API and they are per Tenant base, so for each call to REST API service is used same combination of Key and Secret.

Warning

It is up to developers using Console REST API to restrict or allow user to be able to gain access to REST API. From REST API point of view there is no distinction what user is using REST API since the same Key and Secret is used to gain access to the Console API.

A RESTful example

The HTTP Header is where you include the key and secret fields. Please note the names of these fields; consumer_key and consumer_secret:

1
2
 consumer_key: neFh2vtr2sKH1tvsp0O6
 consumer_secret: 86h1qQEAhwlXydNJTLQj9KK3e5DUZUhoYjLsJKv72k44ZkmF2h

When issuing GET http://mydomain.com/aspire/api/v1/1001/users HTTP/1.1 with the above HTTP Header the result will be JSON describing all the Users belonging to Tenant 1001

Hint

The key and secret for the Host Tenant are created during the installation. You can subsequently access and regenerate these values from within Coach. Please refer to the Coach Installation documentation for further information.

Create, Update and Lookups

The REST API is constructed in a way that to create or update some resource it is needed to get resource by id that will populate the resource form with data, so it can be submitted to the server after changes made by user on form.

With get by id you’ll get new or persisted instance of entity, with all default values already set (only on create) and also all the lookup (read more about about lookups in note below) data will be sent to client.

Hint

The lookup in this sense is collection of key and value pairs needed to set some referenced id in some resource. It is used to populate drop boxes, radio buttons group,... The key of selected or checked item should be used to set some referenced value.

Example would be to create Team, there is need to set it to a belonging Unit (unitId). The Team lookup units will provide you with all Units ids as key and Unit names as value of lookup so it is to set Team’s belonging Unit by choosing one key and setting it to Team’s unitId.

The lookup enumeration keys are integers and ids used are guids.

To set up the form on adding/creating new entity is needed to use get by id and for id is needed to set and empty guid or "00000000-0000-0000-0000-000000000000", this will give you new instance of an entity with default values set and lookups for references loaded so that it can be use for form creation.

REST API Methods and Models

The API methods are the way to obtain data from REST API and models are way this data is represented.

Models

The Models are representation of some resource as its properties and values assigned to it. The Coach API uses two kind of Models:

Domain Models

Used to for create and update domain model, but also for constructing and getting persisted Domain Model.

List Model

The light and normalized version of Domain Model used for lists of resource (usually represented as grid or tabular data) and with fewer properties than Domain Models and instead of reference ids uses human readable name to show in list item.

Hint

Note that Domain Models and List Models are described in lot more details about its properties and behaviors on each API resource page.

Methods

The REST API methods are analogous to HTTP Verbs. For most of resources in REST API you will have this five methods to get most common CRUD (Create Read Update Delete) data from and to server.

GET

Returns a list of all items for requested resource. It is sent as List Model and it is fully read-only data. If there is error on server, it will send error response instead.

GET /:id

Returns a Domain Model representation of resource for particular id. Embedded with resources are lookups, and if is used empty guid it will already set all default values. If there is error on server, it will send error response instead.

POST

Sends the newly created resource Domain Model and after saving it to database returns all the created values (now persisted) as it was called by GET :id. If there is error on server, it will send error response instead.

PUT

Sends the updated resource Domain Model and after saving it to database returns all the updated values (now persisted) as it was called by GET :id. If there is error on server, it will send error response instead.

DELETE

Sends the resources id to server to delete resource. After deletion if everything went well it will not send anything, but if there is error on server, error will be sent as response.

Warning

Note that all resources don’t have support for all methods described before.

  • The Tenant is currently supports only PUT or update (this will change with implementation of multi-tenancy).
  • The Tenant Tree is supports only GET method that or will bring only a Tenant Tree Items.
  • The License is now supports only GET method or will only obtain license from Licensing Server.

HTTP PUT and DELETE Issue

There are known issues with HTTP verbs PUT and DELETE. The PUT and DELETE were not supported on older browsers and PUT and DELETE can be disabled or not disabled by default in IIS Web Server.

Activate PUT and DELETE on IIS Web Server

To activate HTTP PUT and DELETE on IIS Web Server you need to add this part of configuration to the web.config of web application where Coach REST API is hosted.

Hint

Coach REST API is hosted in same location as Coach Silverlight application is hosted.

For IIS 7 and above you can use this configuration to enable PUT and DELETE:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
    <system.webServer>
     <validation validateIntegratedModeConfiguration="false" />
     <modules runAllManagedModulesForAllRequests="true" />
     <handlers>
       <remove name="ExtensionlessUrlHandler-Integrated-4.0" />
       <add name="ExtensionlessUrlHandler-Integrated-4.0"
       path="*."
       verb="GET,HEAD,POST,DEBUG,PUT,DELETE"
       modules="IsapiModule"
       scriptProcessor="C:\Windows\Microsoft.NET\Framework64\v4.0.30319\aspnet_isapi.dll"
       resourceType="Unspecified"
       requireAccess="Script"
       preCondition="classicMode,runtimeVersionv4.0,bitness64"
       responseBufferLimit="0" />
     </handlers>
   </system.webServer>

Warning

Please be aware that this piece of configuration is as-is, it is just example of enabling PUT and DELETE. For more information on enabling the PUT and DELETE in IIS please use IIS documentation or in house System Administrator if you have.

Using API with disabled PUT and DELETE

Activating the HTTP PUT and DELETE is optional step, it is recommended, but optional. If from some case it is problem or it is in house rule to not allow PUT and DELETE or you still supporting browser that are not supporting this verbs then there is a way to sent HTTP PUT and DELETE as POST but with a HTTP Header directive X-HTTP-Method-Override.

UPDATE via POST

To use UPDATE via POST you need to send POST request and in HTTP Header set:

1
X-HTTP-Method-Override: UPDATE

DELETE via POST

To use DELETE via POST you need to send POST request and in HTTP Header set:

1
X-HTTP-Method-Override: DELETE

TODO List

  • Finish Multi-Tenancy for Tenant via Create/Update/Delete + update documentation.
  • Create Tenant Tree of only Unit/Team/Agent items for Schedule Level.