A guide to adding the Use Course State API to Second Nature

User Course State API Overview

The Users Course State API provides a mechanism for end users and third parties to access the status of users course performance. It includes the following key data points:

• Course Score: This represents the average score from all the graded activities within the course.

• Course Passed State: Shows whether the user has achieved the passing score for all the required tasks within the course.

API Endpoints

Base URL

The Base URL for the API requests is:

https://app.secondnature.ai/api/

Authentication

• Every API request must include your API key in the request header.

• For authentication info, see here.

1. Fetch all available courses

• Endpoint: /course-status/

• Method: GET

• URL Parameters: None

Sample Request

curl --location 'https://app.secondnature.ai/api/course-status/' \
--header 'Authorization: Token ' \
--header 'Content-Type: application/json'

Sample Response:

[
  {
    "course_id": "7a14f19c-ca06-426f-b62c-b7a9b5132677",
    "external_course_id": "1cd16929-ac9c-4b56-8407-5ad7f431206e",
  },
  ...
]

2. Fetch course state for all assigned users

• Endpoint: /course-status//

• Method: GET

URL Parameters:

Query Parameters (Optional):

Sample Request:

curl --location 'https://app.secondnature.ai/api/course-status//' \ 
--header 'Authorization': Token  
--header 'Content-Type: application/json'

Sample Response:

[
   {
     "user_email": "john.lennon@thebeatles.com",
     "updated_at": "2022-11-26T00:00:00Z",
     "completed_at": "2022-11-25T00:00:00Z",
     "score": 90,
     "passed": true,
     "course_id": "7a14f19c-ca06-426f-b62c-b7a9b5132677",
     "external_course_id": "1cd16929-ac9c-4b56-8407-5ad7f431206e"
   },
   {
     "user_email": "billy.shears@thebeatles.com",
     "updated_at": "2022-12-26T00:00:00Z",
     "completed_at": null,
     "score": 64,
     "passed": false,
     "course_id": "7a14f19c-ca06-426f-b62c-b7a9b5132677",
     "external_course_id": "1cd16929-ac9c-4b56-8407-5ad7f431206e"
   },
   ...
 ]

Sample Request (with query params):

curl --location \
'https://app.secondnature.ai/api/course-status//?include_external_user_id=true&completed_from=1667260800&completed_until=1669852799' \
--header 'Authorization: Token ' \ 
--header 'Content-Type: application/json'

Sample Response:

[
   {
     "user_email": "john.lennon@thebeatles.com",
     "external_user_id": "user-1234",
     "updated_at": "2022-11-26T00:00:00Z",
     "completed_at": "2022-11-25T00:00:00Z",
     "score": 90,
     "passed": true,
     "course_id": "7a14f19c-ca06-426f-b62c-b7a9b5132677",
     "external_course_id": "1cd16929-ac9c-4b56-8407-5ad7f431206e"
   }
   ...
 ] 

Data Definition

Error Handling

Responses to erroneous requests will include an HTTP status code reflective of the error type, along with a message explaining the cause of the error:

• 200 OK: Returns a JSON object containing the course state of each user.

• 400 Bad Request: Your request is invalid or cannot be processed by the server.

• 401 Unauthorized: Authentication credentials were missing or incorrect.

• 403 Forbidden: You do not have permission to access the specified resource.

• 404 Not Found: The requested resource was not found.

• 500 Internal Server Error: An error occurred on the server which was not the client's fault.

Rate Limiting

The API is rate limited to prevent abuse and ensure service reliability. Users are limited to 5 requests per minute. Exceeding this limit will result in a 429 Too Many Requests response.

Support

For further assistance, please contact our support team at support@secondnature.ai