The SORACOM API Reference guide not only provides details of SORACOM API usage, but allows you to make API calls interactively directly from the reference page. This allows you to easily test the request and response behavior, so that you can quickly integrate SORACOM API into your application.
Below is an example of how to use the interactive API functionality to call the updateSpeedClass API.
Before continuing, please keep the following in mind:
- API calls from the API Reference page will execute against the authorized account.
- API calls executed from the API Reference page are actual API calls, and are not simulated. Please exercise caution when executing calls, such as, for example, terminateSubscriber, as it will perform the same operation as permanently terminating a SIM from the User Console.
- In addition, adding, enabling, or modifying services or options to your account or devices will activate charges associated with each service or option. Please take care to review the pricing structure for each service so as not to incur any unwanted charges.
1. API Authorization
API authentication can be done with either an Authentication Key ID/secret pair, or by using your SORACOM User Console account login information. For convenience, we will use the latter:
Enter your SORACOM User Console account email address and password, then click the Authentication button.
If authentication succeeds, Success will appear below the Authentication button, indicating that we are now authorized to perform API calls from this page. In addition, the API Key, Token, and Operator ID (returned from the authorization request) will automatically be filled in below. Now when we execute an API call from this page, the API Key and Token will automatically be filled in for us.
2. Execute an API call
As a simple test, let's use the updateSpeedClass API to change the speed class of one of our SIM cards.
First, scroll down to the Subscriber API section, and find the updateSpeedClass API:
Click on the API name to show its details:
Under the Parameters section, we can see a list of required or optional parameters for this API call. Here, both the imsi and speed_class fields are required:
We can input the IMSI number of the Air SIM we want to update into the imsi field. For speed_class, let's refer to the model schema on the right-hand side to see how this field should be filled in. We can click the sample model schema to copy it into the speed_class field, and then modify its content to suit our need:
With both parameters filled in, we can click the Try it out! button to execute the API call. By clicking this button, an API request will be made using our API authorization information from earlier, and the parameters we specified in the updateSpeedClass section.
Let's click the Try it out! button and wait for the section to update once the API is excuted.
3. Check the results of the API call
Once our API call has executed, details of the execution and response will appear below. We can refer to the following sections to help guide us while developing our application:
This is an example of the API call used to execute the updateSpeedClass API, with our API Key, Token, and parameters automatically filled in. We can use this as a guide for how to perform the same API call from within our application:
This shows the actual response to our API call. You can check the details to confirm that the API call behaved as expected, and additionally refer to the response body if you want your application to perform additional actions based on the response.
This is the HTTP response code returned from the API call. In our test, we received a HTTP Response Code: 200 (OK) indicating that the API command successfully executed.
If the API call fails, it will return an HTTP Response Code: 4XX or 5XX. For example, a common error is formatting the request parameters incorrectly. When this happens, the API will return 400 (Bad Request), which will let us know to check the formatting of our parameters in the request.
Although the updateSpeedClass is a relatively simple operation, you can now use the API to automate the process for a large number of Air SIMs, or utilize the other API calls to perform custom or more advanced actions. By using the interactive API Reference guide, the Curl templates, and the response bodies, you can quickly integrate the SORACOM API into your application.
In applications where you want a device to be able to make its own API calls, you can utilize the Air Metadata Service option to allow the device to programmatically access, for example, its own IMSI, and subsequently fill in the imsi parameter of an API call. By using this method, you can utilize the same code across multiple devices without having to hard-code IMSI numbers or other information into each device.