How is the SORACOM API Reference structured?

The SORACOM API Reference is organized into API groups, each containing individual APIs, their respective details, and a description of the request and response.

 

API Groups

The API reference allows you to group APIs based on their role. Major groups and their operations are described below.

 API Group Operations
Auth Issue and inspect API Keys, Tokens, and password reset tokens
Credential Create, update, and delete authorization records
Operator Create operators, update registered data, change passwords
Role Set permissions for SAM users
ShippingAddress Operations related to shipment of direct-sale units
User SAM user settings, controls, and permissions
Subscriber Poll, control, and release SIM data
Billing Poll billing data
Payment Create, update, and delete coupon codes and credit card data
EventHandler Poll, create, update, and delete event handlers
Order Check product order status, create estimates, and approve
Stats Poll communications log
Group Group creation, settings, and deletion
VirtualPrivateGateway Create, change, and delete VPG, and operate Soracom Gate

 

API Details

Each individual API detail section is structured as shown below:

  • API Method and Path: the URL path for the REST API method, with parameters in curly braces
  • API Name: the name of the API method, for use in SAM permissions, as well as certain SDKs
  • Summary/Notes: a summary of the behavior of the API method
  • Response Class (Status 200): the structure of the API call response when executed successfully
  • Parameters: a list of required and optional parameters that the API method accepts
  • Response Messages: a list of additional API call responses
  • Try it out!: a button for executing the API method directly from the API Reference page

 

When executing an API method directly from the API Reference page, you must specify an API Key and Token. You can obtain a key/token pair by authenticating your account at the top of the page using an Authentication Key ID/secret pair or your account login information. This simply calls the /auth API method with your given authentication information, and populates the API Key and Token fields with the response.

In addition, the response of the API method call will appear below the button. As the API call is generated dynamically based on the parameters you provide, you can quickly inspect the response to understand the behavior of the API call. A sample curl command is also generated so that you can quickly reference how to call the API from your application.

For more information on how to use the API Reference page for testing the SORACOM API, please refer to: How do I use the SORACOM API Reference to make API calls?

Please note: API calls made on the API Reference page are performed against the authorized account, and are actual API calls and not simulated. Therefore, please use caution when testing, as the API calls will directly affect your account or devices, and may affect connectivity or incur charges based on the API method called.

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request
Powered by Zendesk