Learn - API: an introduction and supporting technical files

The Kallidus APIs give you access to the Kallidus Suite to integrate with other applications, insert and update data, and extract data.

What’s possible with the Kallidus APIs?

The Kallidus APIs give you the ability to:

• Retrieve user record information
• Create and update user records for use across the Kallidus Suite
• Update user records to set Learn specific attributes
• Create and update group records for use in Learn
• Retrieve a list of user records
• Import users into Learn

You can get a full list of the API endpoints available to you by navigating to the API in your browser. See below for more details.

Retrieve user record information

You can retrieve user record information in a paginated way.  This helps ensure that, even when a large amount of data is present, you can retrieve it in batches so as to avoid any technical overload.

The endpoint is powered by GraphQL and is available at the url https://gateway.kallidusapi.com/search. To retrieve data using this API you need to post a constructed simple query – here is an example of a fully formed query. 

Query {person (first:3) {totalCount edges {node { id,

givenName, familyName, email, mobileNumber, importKey,

isEnabled, startDate, leaveDate, jobTitle, username,

Culture, UserFields {index,value}} cursor }}}

The search endpoint supports filtering and for the person return type pagination. The person type can return using the below query. The person connection contains edges that link a record or node with a cursor. The node has the data for the data record while the cursor makes the record's position in the list of return results.

query {

    person {

        edges {

            cursor

            node {

                (specify the fields to be returned)

            }

        }

    }

}

The endpoint also supports the return of pagination information that includes the total count of records and page info. Add the following query fields to the query for the PERSON connection:

pageInfo {

    endCursor

    hasNextPage

    hasPreviousPage

    startCursor

}

totalCount

In order to limit the page results the first and after options. The first option will dictate the number of results returned with using after with an edges cursor will mark the start point to return results from. For example:

query {

    person(first:2) {

        edges {

            cursor

            node {

                Id

            }

        }

    }

}

Full information on how to form graphql queries can be found here

https://graphql.org/learn/queries/

https://graphql.org/learn/pagination/

Next Steps

Consult the API technical specification documents for a list of available endpoints. This is available in the Kallidus Support portal (see attachments to this article)

If you get stuck or need more information, contact the Kallidus Support team in the usual way.

Basics

Accounts and authorisation

To access the API, Kallidus will provide you with a subscription key which you must include in the header on all requests. The header name is: Ocp-Apim-Subscription-Key

Methods and content types

The Kallidus APIs are RESTful. In REST, each resource is represented by a base URL like /commonuser and the HTTP methods GET, POST, PUT and DELETE are used to request data and perform actions on those resources.

For methods that accept request parameters the platform accepts the application/json content type and returns data in application/json format.

Rate limiting

The Kallidus APIs are a key component in our products and are used by many of our customers. To ensure fair usage and protect them from abuse, we apply dynamic IP address throttling. If you receive a 429 Too Many Requests response from the API, your application will need to back off and retry the request.

A basic technique to gracefully handle limiting is to watch for 429 status codes and build in a retry mechanism using an exponential back off schedule. The following Microsoft article provides useful information about handling failures and applying retry patterns:

https://docs.microsoft.com/en-us/azure/architecture/best-practices/transient-faults

Security and penetration testing

 Kallidus performs regular security and penetration testing of all its applications, including the Kallidus APIs, and endeavours to resolve any issues in a timely manner.

By its very nature, testing activities of this kind can lead to service degradation and sometimes complete outages. To ensure a consistent level of service, Kallidus does not permit its customers to undertake any form of security or penetration testing without prior consent.

Response status codes

 The Kallidus API returns standard HTTP status codes for request responses. If an error occurs, more information will be provided in the response.

The list below describes the common success and error responses you should expect from the API.

Learn more in The Academy

To explore other resources and to check for upcoming live Academy events, visit The Academy.