This guide applies to the REST API. If you need help with our GraphQL API, see Getting started with the GraphQL API.
Overview
This guide covers common issues encountered when using the iHasco API. We've used desktop software to interact with the API in a visual way, which can be useful to troubleshoot problems that may not be obvious when working with code.
You should also refer to the detailed API documentation.
Before you start
You'll need:
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 the Auth tab and change it 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'll see a list of users returned in the right panel, similar to the below. Note the 200 OK response code indicating success.
Tip: If you want to save lots of requests and re-use the URL and token, you can save them as environment variables in Insomnia.
Sending data to the API
The API lets you make requests that add or change data. An example is changing a user's name via a PATCH user request.
To make this request, first change 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 Form URL Encoded and adding data fields one at a time. In this example we'll change the first_name and last_name fields. Click Send when the data is defined, and you'll see a 200 OK response code and your updated user data confirmed.
The above example uses a Content-Type of "application/x-www-form-urlencoded" for improved readability on screen. We recommend your code sends data in "application/json" format.
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 by changing the token to something else and sending another request.
Solutions
Check you've entered the token correctly — especially missing characters or spaces surrounding the text.
When using code, check you're sending the required header in the format
Authorization: Bearer YOUR_TOKEN.Check that API access is enabled in your LMS and the token you're using hasn't 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'll receive a 429 Too Many Requests response. The number of seconds you must wait before making a further request is identified in 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 that accepts data is checked to ensure the data is valid and in the expected format. If your request isn't accepted, you'll 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.