○ API - Using UIDs instead of external IDs
Most of the API calls require an external ID for them to work. External IDs are set manually by an administrator and/or designer in the learning environment. If you don't want to set external IDs manually, in many cases you can use an automatically generated UID instead. Exceptions are API calls where you create something new (like a user or course), because you do have to set an external ID for this.
For most calls it is always mandatory to use either an external ID or a UID if it is available. You can see an overview of accepted parameters for each API call on the /apidocs page. UIDs are listed as query parameters (instead of path) and sometimes as formData.
If you want to use a UID in the URL of the API call, it always has to be a query parameter. Only external IDs can be used as a path parameter, which is the default way that we show in the documentation.
Example of external ID as path parameter
https://demo.anewspring.com/api/updateUser/{userID}
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/updateUser/testid
Example of external ID as query parameter
https://demo.anewspring.com/api/updateUser?userID={userID}
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/updateUser?userID=testid
Example of UID as query parameter
https://demo.anewspring.com/api/updateUser?userUID={userUID}
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/updateUser?userUID=c21f7c68-7682-11eb-b67e-06575dd7e8c5
UID of activities
UIDs are generated automatically and are always unique. However, the UID of activities are only unique per template and not per course. This means that the same activity in any course of that template will have the same UID.
You can request the structure of a course or template with the API call GET /getCourseStructure/{ID} or GET /getCourseStructure?UID={UID}. The response will contain an overview of blocks and activities. For each activity you will retrieve the UID and the external ID (if it has been set manually).