Best Practices: JumpCloud API

Read this article for guidance on retrying failed requests to JumpCloud's REST API, as well as best practices for structuring subsequent retry requests. Customizing retry mechanisms based on these recommendations will increase the reliability and dependability of your API calls.

Considerations:

• JumpCloud currently utilizes two versions of APIs. Depending on the type of integration, it may be required to use both V1 and V2 APIs. Please refer to each API doc to understand the functionality available in that API set.

Supported HTTP Request Methods

• GET
• POST
• DELETE
• PATCH
• PUT

Response codes

• 200
• 400
• 401
• 402
• 403
• 404
• 409
• 429
• 500

API Key Rotation

Because API keys are utilized in the development of solutions that interact with the JumpCloud API, and thus are sometimes shared, there are opportunities for these private API keys to be compromised.

Best security practice strongly encourages the API Key associated with your JumpCloud Administrator account to be rotated & re-generated on a periodic rolling basis. While specific security needs and risks will vary for your organization, it’s generally recommended to re-create the API keys on an annual basis. Note that once an API key is rotated, the older key will be invalidated. Code that leverages older API keys will fail and will need to be updated with the new key.

Paginating

When paginating results with "skip" or querying with a "filter", it is highly recommended that you also add "sort" : "_id" to the query parameters. Sorting will ensure that you receive all and only the requested data (i.e., no missing or duplicate results). If you choose to sort by a different field, be sure that field contains unique values.

Error Handling

Request errors, regardless of source, can be categorized as Permanent or Temporary errors.

Permanent errors

Permanent errors will cause a request to always fail. Examples of Permanent errors include:

• Authentication failures: An unauthorized API key is used to authenticate the request
• Incorrect request type: An unsupported HTTP request operator at a given endpoint is being used 
• Unsupported request: The request itself cannot be processed, often due to missing or unsupported data values in the request

Temporary errors

Temporary errors will cause a request to fail temporarily or intermittently. Examples of temporary errors include:

• Service Outage
• Service Maintenance
• Rate limiting

An example of a temporary error would be an HTTP error in the 5xx class. This error can be surfaced if the request is made to an endpoint that may be currently unavailable.

Based on the category of error, the Retry rate & strategy can be determined. This is outlined in the following section: Retry rates

Retry Rates

All network components can be responsible for returning errors. These errors are commonly derived from network hiccups on the server or client, a service disruption on incident, or scheduled maintenance. 

Retry mechanisms are useful for increased reliability and consistency when leveraging JumpCloud APIs. Should a request return an error, correctly configured retry mechanisms ensure that the failed request is retried with consideration to the error response.

The following table outlines retry recommendations based on error classification:

Retry Intervals

Retry requests should always feature a longer interval than the previous retry attempt. Best practice is to implement an exponential backoff to specify exact timing increases between retry requests. An example implementation of an exponential backoff would be to retry the request shortly after a failed attempt. Subsequent requests are recommended to be executed on an exponential basis. For example, if the specified retry interval is 30 seconds, the first retry occurs after 30 seconds. The second retry should occur after 60 seconds, the third retry after 120 seconds, the forth after 240 seconds, and so on. Inadequate retry intervals can prove detrimental for both troubleshooting and client-side error handling.

In addition to these guidelines, several consecutive failed requests should warrant further investigation within the request code before retry is attempted. 

Troubleshooting