Responses can come in 3 different output formats: JSON, XML or Text. To specify which kind of output you would like, you will find more information in this article.

Response codes

For POST requests, you will receive a response code 200 if the request was successful. If it was not successful, you will receive another response code. There is more information about this below.

For GET requests, you will receive a response code 200 along with the required information, if this is available. If it's not available, you will receive another response code. There is more information about this below.

Success

By default, when a POST request is successful, you will only receive response code 200 without any output from the API.

It is possible to receive a success message in the specified output format, by adding the parameter _returnSuccessMessage with value true to the URL.

Example: Successful API call without _returnSuccessMessage

API call:

POST https://<domain>/api/addUser/1234567
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
login=johnwatson@example.com
firstName=John
lastName=Watson
Output:
Response code: 200
Example: Successful API call with _returnSuccessMessage

API call:
POST https://<domain>/api/addUser/1234567?_returnSuccessMessage=true
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
login=johnwatson@example.com
firstName=John
lastName=Watson
Output:
Response code: 200
{"success":"OK"}
Errors
An API call can fail for different reasons. The API will then send a response code and an error message. By default, this error message is not formatted, but plain text.
It is possible to receive the error message in the specified output format, by adding the parameter _formatErrors with value true to the URL.
Response code 400
This means that a required parameter is missing or that a parameter contains an invalid value.
Example: Missing parameter with _formatErrors

API call:
POST https://<domain>/api/addGroup/ABCD?_formatErrors=true
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
type=Student
name=ExampleGroup
Output:
Response code: 400
{"error":"Missing parameter: name"}
Response code 403
This means that the API key is missing, incorrect or that it can't be used from your IP address.
Example: Missing API key

API call:
POST https://<domain>/api/addGroup/ABCD
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
type=Student
name=ExampleGroup
Output:
Response code: 403
No API key specified
Response code 404
This means that the URL doesn't exist (e.g. a part is missing), or the object that the URL refers to doesn't exist (e.g. the user doesn't exist).
Example: User with specified email address does not exist

API call:
POST https://<domain>/api/initializeId/johnwatson@example.com/1234567
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
Output:
Response code: 404
User does not exist
Example: API call does not exist
API call:
GET https://<domain>/api/nonExistingCall
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Output:
Response code: 404
Unknown command: nonExistingCall
Response code 409
This means that the state of the object makes it impossible to perform an action. For example: Adding a user that already exists.
Example: User already exists
API call:
POST https://<domain>/api/addUser/1234567
Headers:
X-API-Key: ****
Content-Type: "application/x-www-form-urlencoded"
Body:
login=johnwatson@example.com
firstName=John
lastName=Watson
Output:
Response code: 409
User already exists
Response code 500
This means that an error occurred on the server side.
To test API calls and see what kind of responses and response codes you will receive, you can use the /apidocs page of your learning environment. More information about this in the next article:
API - Using /apidocs