Troubleshooting the Client API

This guide covers common issues encountered when using the iHASCO API. We have used desktop software to interact with the API in a visual way. This can be useful to troubleshoot problems which may not be obvious when working with code.

You should also to refer to the detailed API documentation

Before you start

You will need:

• API client software. This guide assumes you are using Imsomnia. You could also use Postman or cURL via a terminal
  
  
• An account in our LMS and an API access token. (see How to enable/disable the Client API)
  
  
• Some users and course results registered in your LMS
  
  

Your first request

Requesting a list of your users is a simple way to verify your access.

Start Insomnia and select New Request from the + link

Call the request "GET users" and set the type to GET. Click Create

Click on the Auth tab and change to Bearer Token. Enter your token in the TOKEN box and ensure enabled is checked.

Now enter "https://api.ihasco.co.uk/users" as the request URL and click send. You will see a list of users returned in the right panel similar to the below. Note the 200 OK response code indicating success

Sending data to the API

The API allows you to make requests which add or change data. An example of this is changing a user's name via a PATCH user request.

To make this request, first adjust the  Verb for your request to PATCH and add a slash followed by a user identifier to the URL. The identifier can be an ID or email address.

You must then define the data you wish to send. This is best shown in Insomnia by changing the request type to  From URL Encoded and adding data fields one at a time. In this example we will change the first_name and last_name fields. Click Send when data is defined and you will see a 200 OK response code and your updated user data confirmed.

Problem: 401 Unauthorized response

This is caused by either an incorrect token, or the token not being provided in the correct manner. You can see an example of this by changing the token to something else and sending another request.

Solutions

• Check you have entered the token correctly - especially missing characters or spaces surrounding the text
  
  

• When using code, check you are sending the required header in the format

  Authorization: Bearer YOUR_TOKEN 
  
  

• Check that API Access is enabled in your LMS and the token you are using has not been removed.

Problem: 429 Too Many Requests response

Requests to the API are limited to 200 per minute per request token. Your remaining requests within that limit are provided in a response header named x-ratelimit-remaining. You can see these headers in Insomnia by clicking the Headers tab in the response panel.

If you exhaust your request allowance, you will receive a 429 Too Many Requests response. The amount of seconds you must wait before making further request will be identified as a retry-after header. Your code will need to look for this outcome and react accordingly.

Solution

Wait the required number of seconds before making another request.

Problem: 400 Bad Request response

Any request which accepts data will be checked to ensure that data is valid and in the expected format. If your request is not accepted you will receive a 400 Bad Request response code along with a summary of errors encountered.

The example below shows an attempt to update a user with an invalid email address. Note the 400 Bad Request response code .

Validation errors are common and your code should be written to take appropriate action when one is encountered.

Solution

Check the format of your data against the documentation and adjust as required.

Support

If you encounter an error that cannot be solved and explained by the above, please contact a member of the Technical Support Team. In order to investigate we will need:

• Your account name or Client ID (NOT your access token - keep that secret just like you would a password)
  
  
• A copy of the request that was sent and which URL it was sent to
  
  
• The response code you received
  
  
• The response data you received
  
  

In most cases a screengrab such as the example above is sufficient.