Best Practices

The following are a list of best practices which are suggested when building a client to USTA:

Check for a 401 after every API request
- Get a new token - once only
- Retry the API request - once only
Protect your access tokens and refresh tokens
- Once delivered to the client app, the tokens provide access to your information an the client app is responsible for keeping them safe
Access tokens are valid for 1 hr before requiring refresh via refresh token
Always use HTTPS rather than HTTP
API raises exceptions for many different reasons, such as invalid parameters, authentication errors, and connection failure. We recommend writing code that gracefully handles all possible API exceptions. See error codes page for a complete list.
Large data sets are paginated. Read the data in chunks following pagination implementation and handle one chunk at a time.

Token TTLs

The following are time-to-live (TTL) settings for token expiration. The JWT token has a claim (field) that needs to be checked to when it expires. It is expressed as a NumericDate measured in UTC time format.

Token	TTL	JWT Claim

Token	TTL	JWT Claim
Access Token	1 Hour	exp
Refresh Token	30 Days	exp

Working With JWT Tokens

JWT tokens are encrypted JSON format and contain fields called claims. Once you generate an Access Token, you can examine the contents at http://jwt.io . This is a valuable debugging tool.

Bound Mode/Authentication Code

Check For 401 Status Response To Determine Whether To Use Refresh Token

One simple way t deterine if the Access Token has expired is to check each API call for a 401 status in the response. In this case, use the Refresh Token to get a new short-lived Access Token without additional authentication.

Keep Track Of Expiration Time To Live

A more involved method is to track the expiration TTL when you retrieve your Access Token. If the time has expired, then use the Refresh Token to get a new short-lived Access Token and repeat the API call with the new Access Token.

See: https://ustadigital.atlassian.net/wiki/spaces/DEV/pages/edit-v2/998604834

Unbound Mode/Authentication Code

Check For 401 Status Response To Determine Whether To Request A New Access Token

One simple way t deterine if the Access Token has expired is to check each API call for a 401 status in the response. In this case, call the Token endpoint to get a new a new short-lived Access Token without additional authentication and repeat the API call.

Keep Track Of Expiration Time To Live

A more involved method is to track the expiration TTL when you retrieve your Access Token. If the time has expired, call the Token endpoint to get a new a new short-lived Access Token without additional authentication and repeat the API call.

See: https://ustadigital.atlassian.net/wiki/pages/createpage.action?spaceKey=DEV&title=Machine%20to%20Machine%20%28Unbound%20Access%29&linkCreation=true&fromPageId=1001128100

Pagination

Pagination is implemented on endpoints that contain potentially large result sets.

"pagination": {
    "currentPage": 0,
    "pageSize": 0,
    "totalPages": 0,
    "totalResults": 0
}

Where:

currentPage - the index of the page within the set.
pageSize - the number of items on each page.
totalPages - the upper bound of pages for looping.
totalResults - the aggregate number of items returned across all pages.

On This Page:

1 Best Practices
2 Token TTLs
3 Working With JWT Tokens
- 3.1 Bound Mode/Authentication Code
  - 3.1.1 Check For 401 Status Response To Determine Whether To Use Refresh Token
  - 3.1.2 Keep Track Of Expiration Time To Live
- 3.2 Unbound Mode/Authentication Code
  - 3.2.1 Check For 401 Status Response To Determine Whether To Request A New Access Token
  - 3.2.2 Keep Track Of Expiration Time To Live
4 Pagination