Tips and Tricks to Customize Your IoT Deployment with the Soracom API
Written by: Steve Hardy
Published: May 11, 2023
Integrating with the Soracom API can be a challenge for some engineers, but it doesn’t have to be. In this blog post, we will share some tips that will help you navigate the API more easily.
Before we dive into the tips, you may want to check out the Soracom API Usage Guide. This comprehensive guide contains essential information and can provide more insight into the API and its capabilities. If you’re new to the API, we also recommend reading our previous blog post, “How to Use the Soracom API,” which provides a useful overview of the interface.
Tips for Authentication API
The Authentication API is the base of access to all functional APIs. Here are some key points to keep in mind when using it:
Use “Authentication Key ID” and “Authentication Key Secret” for Programmable Access.
The Soracom API authenticates requests with an “API Key” and an “API Token.” The API Key and API Token describe who the subject of the request is and what authority they have, respectively, leaving Soracom to verify the contents of each request.
The API key and token are issued using the “Authentication Key ID” and “Authentication Key Secret” that have been allocated in advance. We recommend using the Authentication Key ID and Authentication Secret for programmable API access, such as integration with business systems. Other options are also available for authentication, including Email Address and Password, Operator ID, SAM Username, and Password.
Set an Appropriate Expiration Date for API Tokens and Cache Them
In scenarios where Soracom API needs to be accessed continuously, such as when integrating with a business system, creating an API token each time the functional API is accessed can create performance issues.
We recommend setting an appropriate API token expiration date for your use case and cache the token for the period. The default expiry time is 86400 seconds (24 hours) but can be set between 180 to 172800 seconds (48 hours). The API token will contain the expiry information in JSON Web Token format.
Tips for Setting Permissions
When creating Soracom Access Management (SAM), users can be assigned individual roles and access privileges. For example, your technical department can have full access to the User Console, while your accounting department may have read-only access to billing and payment information.
Once a SAM User authentication method has been enabled, an authorized user or application integration will be able to access the Soracom User Console, Soracom API, or Soracom CLI. However, by default, the SAM User account will not include any permissions to perform actions. If desired, you can add permissions to SAM Users in order to allow (or deny) access to different parts of the User Console, API, or CLI at a lower date.
The permissions of the user, like expiry time, are stored in the API token in JWT format
Tips for Monitoring API Usage
When using Soracom in a multi-user organization, you may want to periodically check for indications of unauthorized access. Audit Logs provide detailed information about calls to the Soracom API performed against your Soracom account, including access to the User Console and Soracom CLI usage. When combined with Soracom Access Management (SAM), Audit Logs can be used to check the behavior of SAM users.
Audit Logs will record the following information:
- The timestamp of when the API was accessed
- The IP address (IPv4/IPv6) used to call the API
- The username corresponding to the authenticated user
- If the authenticated user is the root account, <root user> will be recorded
- If the authenticated user is a SAM user, the username will be recorded
- The path of the API request
- The status code of the API request
You can also access Audit Logs using the Soracom API or CLI in order to integrate a periodic audit procedure as part of your operations.
Tips for Request Retry on the Soracom API
In this section, we will introduce the types of retries that should be performed for stable API operation:
Errors Requiring Retries
Depending on the response status code from the Soracom API, a retry may be required. Errors that require retries can be broadly categorized into the following two types:
- The Soracom API is experiencing a problem.
- There is a rate limitation on access to the Soracom API.
Both of these problems will take time to resolve. When an error is detected, please consider a mechanism to temporarily halt access to the Soracom API and retry after some time has passed.
When There is a Problem With the Soracom API
If the response from the Soracom API times out or the response status code is between 500-599, there is a problem with the API, and a retry is required.
The recommended retry strategy is Full Jitter Exponential Backoff. This involves increasing the delay between retries exponentially and adding a random jitter to avoid synchronization between multiple clients. It’s essential to consider retrying the request after some time has passed and back off if the error persists.
When There is a Rate Limitation of Access to the Soracom API
There are rate limits for accessing the Soracom API. When rate-limited, the response status code will be 429. If you receive this error, wait for the number of seconds specified in the X-Soracom-Ratelimit-Seconds-Before-Refresh response header, and then retry.
Errors That Should Not Be Retried
If the API response has a status code in the 400 range (400-499, excluding 429), do not retry the same request. A few common errors that occur in this range include:
- When the API token has expired
- The account of the API token and the account of the accessed resource are different (incorrect resource specification)
- Required request parameters are missing
- An Incorrect HTTP method has been specified
If you receive a status code in the 400 range, do not retry and check the contents of the request.
Never Be Afraid to Ask for Assistance With The Soracom API
In conclusion, integrating with the Soracom API can be challenging for engineers, but by following the tips provided in this article, it becomes a lot easier.
- The Authentication API is the base of access to all functional APIs, and engineers should use “Authentication Key ID” and “Authentication Key Secret” for programmable access.
- It is also recommended to set an appropriate expiration date for API tokens while caching them.
- When it comes to request retry, errors requiring retries should be handled using a Full Jitter Exponential Backoff strategy, considering the delay between retries and adding a random jitter to avoid synchronization between multiple clients.
By implementing these tips, engineers can have a better understanding of the Soracom API and ensure stable API operation.
………………
Got a question for Soracom? Whether you’re an existing customer, interested in learning more about our product and services, or want to learn about our Partner program – we’d love to hear from you!
