Skills Base includes a REST API which is available to paid license holders and provides a way for organizations to programmatically access their data in Skills Base. The API uses JSON formatted data for communications.
Enabling the API
You can enable the Skills Base REST API for your instance via the following steps:
- Navigate to [Administration > Settings > API > Manage API Keys]
- 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:
- Navigate to [Administration > Settings > API > Manage API Keys]
- 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:
Parameter | Description |
access_token | Your access token which will be used later to invoke API methods |
token_type | Will always be set to "Bearer" |
expires_in | Indicates how long until the token expires (in seconds) |
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:
- Request an access token
- Perform API requests
- Repeat from step 2 until a HTTP 403 reponse is received
- 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
Content type | Use header | Support |
Form-encoded data | Content-Type: application/x-www-form-urlencoded | API 1.0 only |
Json-encoded data | Content-Type: application/json | API 1.0 and API 2.0 |
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:
Name | Data type | Description |
status | string | Will contain the string "success" when the operation was successful or "error" when the operation could not be performed. |
message | string | This parameter will appear only when there is a message returned by the API (usually in association with an "error" status. The message will provide additional information about the API call that was made. |
data | object|array|null | Contains any data that is returned by the API. Note that data is limited to 500 records (see "Data limit" below). |
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
Type | Accepted values |
integer | Any whole number |
decimal | A number with 2 decimal places |
float | A number with greater than 2 decimal places |
string | Any string |
date | A date in the format YYY-MM-DD |
boolean | true or false |
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.