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:

_keyIt'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.
_returnSuccessMessageIf 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.
_formatErrorsIf 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.
_prettyIf 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).
AcceptYou can use this to specify the output format. The accepted values are:
  • application/json
  • application/xml
  • text/xml
  • text/plain

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%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?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-d6b8fd5ffb27
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?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-16

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

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:

API - Responses and response codes