○ API - Responses and response codes
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/1234567Headers:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:login=johnwatson@example.com firstName=John lastName=WatsonOutput:
Response code: 200
Example: Successful API call with _returnSuccessMessage
API call:POST https://<domain>/api/addUser/1234567?_returnSuccessMessage=trueHeaders:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:login=johnwatson@example.com firstName=John lastName=WatsonOutput:
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=trueHeaders:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:type=Student
Output:name=ExampleGroup
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/ABCDHeaders:Body:
X-API-Key: ****Content-Type: "application/x-www-form-urlencoded"type=Student name=ExampleGroupOutput:
Response code: 403No 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/1234567Headers:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:Output:
Response code: 404User does not exist
Example: API call does not exist
API call:
GET https://<domain>/api/nonExistingCallHeaders:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Output:
Response code: 404Unknown 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/1234567Headers:X-API-Key: **** Content-Type: "application/x-www-form-urlencoded"Body:login=johnwatson@example.com firstName=John lastName=WatsonOutput:
Response code: 409User 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: