○ API - Calling the API and the output format
You can call the API using HTTPS, with this base URL:
https://<domain>/api/
<domain> is the domain of the learning environment (example: demo.anewspring.com). The base URL is followed by the function that you want to execute and possibly some parameters.
Make sure to use HTTPS when connecting to the API.
The API accepts HTTP requests with the GET and POST method. We advise POST requests if you also want to send data. The encoding of the parameters should be UTF-8.
An API key is always required. You can send this as a header (recommended) or as a parameter in the URL, but that could potentially be a security risk in some situations.
Parameters in the URL
These are general parameters that you can add to the API call URL:
_key | It's a better practice to place the API key in the X-API-Key header as described below, but it's technically also possible to use the _key parameter for the API key. If you use both, the _key parameter will get priority. |
_returnSuccessMessage | If you set this to true, you will also receive JSON or XML output if the API call is successful. By default, this is set to false and you only receive response code 200. |
_formatErrors | If you set this to true, you will receive any possible error messages as JSON or XML output. By default, this is set to false and sends text. |
_pretty | If you set this to true, the output will be formatted to be easier to read. This can be useful for debugging purposes. |
Headers
These are the headers that you can add to your request:
X-API-Key | Use this for the API key. Alternatively, you can use the _key parameter as described above. If you use both, the _key parameter will get priority. |
Content-Type* | This should be either application/x-www-form-urlencoded or multipart/form-data (if you need to include a file). |
Accept | You can use this to specify the output format. The accepted values are:
There are other ways to specify the output format, see information below. |
*Required
Example in cURL:
curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "login=testuser&firstName=test&lastName=test" https://demo.anewspring.com/api/addUser/testid
API call specific parameters
The API documentation lists all parameters that you can send with a POST. There are two parameter types: path and formData. If we take the API call POST /updateCourse/{ID} as an example, the parameter ID is a path parameter and the other parameters that you find on the /apidocs page are formData parameters.
path parameters
These are usually external IDs. By default, you would add the value for these parameters after a / in the URL.
Alternatively (for example, if an external ID should contain a /), you can also add them in a query string.
Make sure to urlencode special characters.
Examples for /updateCourse/{ID}
ID = "1234 ABC"
In the path: /updateCourse/1234%20ABC
curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "startDate=2020-12-16&expireDate=2021-06-16" https://demo.anewspring.com/api/updateCourse/1234%20ABC
In the query string: /updateCourse?ID=1234%20ABCcurl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "startDate=2020-12-16&expireDate=2021-06-16" https://demo.anewspring.com/api/updateCourse?ID=1234%20ABC
query parameters
Path parameters can also be used as query parameters instead (see example above), but the only parameters that should always be sent in the query string are UIDs. In many cases, these can be used as an alternative to external IDs.
Example for /updateCourse?UID={UID}
UID = "1807abf8-f34b-404d-8bb3-d6b8fd5ffb27"
In the query string:
/updateCourse?UID=1807abf8-f34b-404d-8bb3-d6b8fd5ffb27curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "startDate=2020-12-16&expireDate=2021-06-16" https://demo.anewspring.com/api/updateCourse?UID=1807abf8-f34b-404d-8bb3-d6b8fd5ffb27
formData parameters
By default you would send these in the body as application/x-www-form-urlencoded or multipart/form-data.
Alternatively, you can also send these in the URL as a query string.
Example for /updateCourse/{ID} with x-www-form-urlencoded
startDate = "2020-12-16"
expireDate = "2021-06-16"/updateCourse/1234
body:
startDate=2020-12-16&expireDate=2021-06-16curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST -d "startDate=2020-12-16&expireDate=2021-06-16" https://demo.anewspring.com/api/updateCourse/1234
Example for /updateCourse/{ID} with a query string
startDate = "2020-12-16"
expireDate = "2021-06-16"/updateCourse/1234?startDate=2020-12-16&expireDate=2021-06-16
curl -H "X-API-Key: ************************************" -H "Content-Type: application/x-www-form-urlencoded" -X POST https://demo.anewspring.com/api/updateCourse/1234?startDate=2020-12-16&expireDate=2021-06-16
Output format
The API supports 3 output formats for responses:
- JSON
- XML
- Text
The default output is JSON, so that's what you will receive if you don't specify the output.
Besides using the Accept header (see above), you can also specify the output format by adding an extension to the API call. This can be .json, .xml or .txt.
Example:
You want to check if a user (with external ID 1234567) exists and you want the output as XML.
The API call to get this information is: GET /userExists/{userID}
You can get the output as XML by adding the extension .xml to the API call:
GET https://<domain>/api/userExists.xml/1234567
If you use both the Accept header and the extension, the extension will have priority.
The next article explains more about the responses and response codes: