API introduction

Enabling the API

You can enable the Skills Base REST API for your instance via the following steps:

1. Navigate to [Administration > Settings > API > Manage API Keys]
2. Click the "+Add client ID" button

An API key and Secret will be generated which are used to obtain an access token (refer to "Authentication" below).

You can disable the API by clicking the "Delete keys" button. Note that this will delete the keys that have been generated and break any active integrations that you have. If you enable the API again different keys will be generated which means you will have to update the keys in your code before your integration(s) will start working again.

API Host

Your Skills Base instance is directly associated with a specific API host. If you use the wrong API host, you will not be able to authenticate.

To view your API host:

1. Navigate to [Administration > Settings > API > Manage API Keys]
2. Retrieve the API host from the "API Host" field. In the example below the API Host is https://api.skills-base.com

Use this host for all API calls.

Authentication

The Skills Base REST API implements the OAuth 2.0 standard, and specifically the Client Credentials grant type, for authentication of client requests.

Obtaining an access token

Access Tokens are used to authenticate API requests. Obtaining an access token is achieved by performing a HTTP POST including your API key and secret as form encoded data in the body of the request to the endpoint listed below. OAuth standards also require that you specify the grant type (as "client_credentials").

Access tokens expire (see "Access Token expiry" section below), and there is also a limit on the number of access tokens that can be active at any time (see "Access Token limit" section below). If you exceed the limit the API will refuse to issue any further tokens until an active one expires. Note that access tokens expire after a period of time that is specified in the JSON response (in seconds). To avoid hitting the token limit, it is important to keep using the same access token until it expires (see recommeded approach in the "Access token limit" section below).

Endpoint

/oauth/access_token

A sample access token request:

POST /oauth/access_token HTTP/1.1 
Host: example-api.skills-base.com 
Accept: */*
User-Agent: OAuth gem v0.4.4
Connection: close 
Content-Type: application/x-www-form-urlencoded
Content-Length: 175

grant_type=client_credentials&client_id=xxxxxxxxxxxxx&client_secret=xxxxxxxxxxxxx

A sample response:

HTTP/1.1 200 OK
Date: Thu, 25 Feb 2016 05:54:06 GMT
Server: Apache
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Content-Length: 99
Content-Type: application/json

{"access_token":"xxxxxxxxxxxx","token_type":"Bearer","expires_in":3600}

The parameters in the access token response are:

Access Token expiry

All issued access tokens expire within a given timeframe that is indicated (in seconds) in the response provided when the token is issued.  It is not neccessary to track this time or attempt to calculate when an access token is due to expire, and attempting to do so will likely be inaccurate.  Instead, we recommend to continue using an issued access token until a HTTP 403 response is returned, indicating that the access token is no longer valid.  At that point it is possible to request a new access token via the same method detailed in the above section "Obtaining an access token".

Since the Skills Base API implements the OAuth 2.0 Client Credentials Grant standard for authentication, please note that "Refresh tokens" are not used, as that standard stipulates that "refresh token(s) SHOULD NOT be included" in responses, and they are also not useful or neccessary in this circumstance.

As such, the following sequence is recommended for interacting with the Skills Base API:

1. Request an access token
2. Perform API requests
3. Repeat from step 2 until a HTTP 403 reponse is received
4. Once a HTTP 403 response is received, repeat from step 1

Using this recommended approach, only one active access token should ever be required per integration.

Making API calls

Once you have an access token, you can begin making API calls. There are some requirements for API calls:

• A valid Access Token must be passed as a HTTP Authorization: Bearer header. Ensure that "Bearer" starts with a capital "B".
• You must use the https protocol for all API requests.
• You must specify a valid content type

Supported request body content types 

Example API call

POST /1.0/people/search HTTP/1.1
Host: example-api.skills-base.com
Content-Type: application/json
Authorization: Bearer xxxxxxxxxxxxxxxxx
Content-Length: 28

{
    "first_name": "T*"
}

API Responses

The following fields are included in API responses:

Sample API response:

HTTP/1.1 200 OK
Date: Thu, 25 Feb 2016 05:54:06 GMT
Server: Apache
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Content-Length: 369
Content-Type: application/json

{"status":"success","data":[{"id":1,"first_name":"Test","surname":"User","email":"test@example.com","full_name":"Test User","team_id":null,"role_id":null,"location_id":null,"security_group_id":1,"skillset":"all","last_self_assessment":"2014-03-29","last_supervisor_assessment":null,"source":"local","login_enabled":true,"last_login":"2015-05-21","locked":true}]}

Data types

Following is a summary of the data types used and supported by the Skills Base API

API limits

Rate limit

The Skills Base API is limited to a certain number of requests per time interval. You can check your rate limit viia the "API Keys" page in your Skills Base instance (log in as an Administrator and click [Admin > Settings > API > Manage API keys]).  If you exceed the limit, the API will respond with HTTP/1.1 403 Unauthorized and the "message" parameter will contain the string "API rate limit exceeded. Try again in x minute(s)"

Don't exceed the rate limit for a prolonged period of time as it can be interpreted as a Denial of Service attack which may result in your IP address being blocked. Pay particular attention to parts of your script that retry failed requests (eg: invalid access token, API rate limit exceeded, etc). If there is no delay between retries you may find your script flooding the API with requests in excess of the rate limit.

You can check the rate limit status via the following two HTTP headers that are returned in the reponse from API endpoints:

• X-RateLimit-Remaining - The number of requests that you have reamining in the current interval
• X-RateLimit-Reset - Indicates the time that the current interval ends and the counter will be reset (as a Unix timestamp)

Data limit

The API will return a maximum of 500 records for GET requests. If you receive a response with 500 records, you can access the further records by making a subsequent API call using the "start_index" parameter.

start_index parameter

This parameter can be appended to the querystring of GET requests and is used to specifiy the starting index when fetching records. Records in the Skills Base API are zero-indexed, so to fetch records 501 to 1001 for example:

GET /people?start_index=500

Access Token limit

The API limits the number of access tokens that are active at any one time. You can view your access token limit in [Administration > Settings > API > Manage API Keys > Token limit]. Once the allocated number of access tokens have been issued no further tokens will be issued until at least one of the issued tokens expire. If you attempt to generate a new access token when you have already reached the maximum number of active tokens the API will respond with HTTP 403 status and a message stating "Access token allowance exceeded". In this case you must use one of the existing issued tokens or wait for at least one of those issued tokens to expire before a new one can be generated.

Search APIs

Search APIs provide additional feature to help you search for records.

Wildcards

For fields that support wildcards, you can use the asterix character to search for partial strings. For example, to search for people beginning with the letter "s":

"s*"

Greater Than and Less Than operators for date fields

The Search API offers additional functionality for fields with the "date" data type. The greater than (>) and less than (<) logical operators can be included at the beginning of the date to specify a date range. For example, to search for records before the 1st of January 2016:

"<2016-01-01"

To search for records in 2015:

[">2014-12-31", "<2016-01-01"]

Case insensitivity

The search APIs are case insensitive

API changes

Any changes we make to APIs will ensure backwards compatibility. If we need to make significant changes to an API that would break existing integrations we will release a new API and maintain both until such time that the old one can be phased out without impacting customers.

Please note that we may add features to APIs and so you should not rely, for example, on an object having a set number of properties. Always ensure your integrations will not be affected by the addition of properties to objects used by the API.