Cellular IoT Questions? Ask Soracom! Vol 2
Written by: Cody Lirette
Published: February 25, 2020
This is the second edition of Ask Soracom! We receive tons of questions from our customers and want to start answering them using articles so that others can learn from them as well.
One popular question that we receive is how to reverse lookup API documentation. To answer that, we’ll be introducing the API corresponding to each SORACOM service.
You may know that SORACOM Air and Beam are the first services released by Soracom; however, there is one more that is just as important: the API. From the beginning, we wanted to provide simple APIs that can be used to manage the Soracom platform and all of its services so that developers can effectively scale using programs and scripts
The most obvious use case for the API is the SORACOM User Console which customers should be quite familiar with. Almost all functions that are commonly used in the user console can be called with the API.
However, with the release of SORACOM Canal, Direct, Door, Endorse, Funnel, Funk, Gate, Harvest, Inventory, Junction, Krypton, Lagoon, Napter and the release of many other services, the correspondence between service names and APIs has become difficult to understand.
In the long term, we want to add API and SORACOM CLI procedures to the Getting Started documents of various services to make them easier to use.
Here’s how to find API documentation based on each specific SORACOM service that you use.
1. API for SORACOM services
SORACOM offers not only SORACOM Air, which provides cellular connectivity but also network and application services that enable the construction of secure IoT / M2M systems.
Connectivity
SORACOM Air is the foundation of the platform as it provides connectivity for IoT. The following APIs are used for registration, cancellation, data acquisition, group change, tag addition, etc. of SIM itself, LoRaWAN device and SigFox device.
| Service | Target API | Notes |
|---|---|---|
| Air for Cellular | Subscriber | The SIM that is managed using the SORACOM API as described in the Usage Guide is called Subscriber (SIM stands for Subscriber Identity Module). |
| Air for LoRaWAN | LoraDevice, LoraGateway, LoraNetworkSet | |
| Air for Sigfox | SigfoxDevice |
There are also some related APIs as well.
| Function | Target API | Notes |
|---|---|---|
| Event handler | EventHandler | This function can execute email notification, change speed class, and execute AWS Lambda function based on data transfer capacity threshold for specific SIM, specific group, specific tag and all SIMs. |
| Search | Query | You can search for SIM and SigFox devices and obtain SIM traffic ranking. |
Network services
AWS customers can connect to the virtual private cloud and SORACOM platform directly using Canal. Alternatively, users can connect using a dedicated line with Direct, use a virtual private line with Door, or build a device LAN connection between your system and the device with Gate.
In addition, there is Soracom Junction which allows users to control traffic at the packet level and Soracom Napter, which enables easy and secure on-demand remote access. Besides Napter, there is no API to operate each service directly.
| Service | Target API | Notes |
|---|---|---|
| Canal, Direct, Door, Gate, Junction | VirtualPrivateGateway | VPG is a crucial component to using multiple SORACOM services as it’s a dedicated gateway that can eliminate public internet access, keeping your network closed. |
| Napter | PortMapping | This can be used to assign address ports for NAPT (Network Address Port Translation) |
Application services
There are more application services than network services but they are broadly divided into three categories: data transfer, data utilization, and device support.
Data transfer
SORACOM Beam can offload high-load processing such as encryption and connection destination settings to the cloud. Plus, SORACOM Funnel can be used as a cloud adapter to directly transfer data from devices to specific cloud services – not to be confused with Funk which executes specific cloud service functions.
| Service | Target API | Notes |
|---|---|---|
| Beam, Funnel, Funk | Group | In each case, a SIM group / LoRa group / SigFox group is created, the target service is set, and the target SIM or device is used by using it. Therefore, the Group API is used. If you are unfamiliar with this API, first create a group in the user console, set the desired settings, and then see how the settings are entered with the getGroup operation of the Group API. |
Data utilization
There are two types of data utilization applications: SORACOM Harvest, responsible for collecting and storing IoT device data, and Lagoon, which can create visual dashboards generated from the collected data.
| Service | Target API | Notes |
|---|---|---|
| Harvest Data | Group, DataEntry | This is used when acquiring SORACOM Harvest Data data. |
| Harvest Files | Group, FileEntry | This is used when acquiring data from SORACOM Harvest Files. |
| Lagoon | Lagoon | The data displayed in the dashboard is obtained above and this API is used to control users and plans (Free / Maker / Pro). |
Device support
SORACOM can be used as an authentication provider to support secure provisioning (initial setting) of IoT devices. Soracom Endorse uses device authentication services, Soracom Inventory deploys device management based on OMA Lightweight M2M (LwM2M) and Soracom Krypton verifies devices using SIM authentication.
| Service | Target API | Notes |
|---|---|---|
| Endorse, Krypton | Group | Endorse and Krypton are used similar to the above services so they fall under the Group API as well. |
| Inventory | Device, DeviceObjectModel | It’s easy to remember that the service managing devices is called Inventory! |
Auxillary functions for each service
Auxiliary functions commonly used in connectivity, network services, and application services can also be controlled by the API.
| Function | Target API | Notes |
|---|---|---|
| Authentication information | Credential | For example, you can collectively register the authentication information of the connection destination used in Beam. This is a wonderful feature that can be controlled on the cloud side without having to have authentication information on the device. |
| Error log | Log | The logs that can be seen in the “error log” of the user console can also be obtained from the API. |
| Audit log | AuditLog | This is the log used when accessing remote access with Napter; a new feature that has been handy for many of our customers. |
| Usage calculation | Stats | It is often used to check SIM traffic. Check the usage details of each service that cannot be obtained from Stats by downloading the billing details CSV from Billing: exportBilling. |
2. API for managing billing, payment, and ordering
On the Soracom platform, billing, payment, and order management can also be changed using the API. In this case, it may be troublesome to see or change, so it is recommended to create individual users with the Soracom Access Management function for normal operation and control the operation authority.
| function | Target API | Notes |
|---|---|---|
| Billing | Billing | Monthly, daily and past billing information can be obtained here. You can also get detailed billing details CSV with exportLatestBilling operation . |
| Payment | Payment | You can register coupons, check payment history, and get past usage details. |
| Order | Order | Or automatically order a SIM based on availability from the API. You can also use the registerOrderedSIM operation to confirm receipt of a SIM. |
| Shipping address | ShippingAddress | You can also register / delete shipping destinations using the API. Automatically order SIMs and ship them to any destination. |
3. API for user management
User Management is also possible through the API!
| Function | Target API | Notes |
|---|---|---|
| Operator | Operator | SORACOM platform terminology uses analogy as a telecommunications carrier. As a result, the account used to log in with the SORACOM user console corresponds to Operator. |
| SAM user | User | When building a large-scale IoT system, administrators and programs with various roles are assumed, and it’s not necessary to grant all access rights to all administrators and programs. By using SAM, an API that can create and use a “SAM user” who has limited access rights can be set under an operator who can perform all operations related to the account. I highly recommend it. |
| Role | Role | You can control the roles assigned to SAM users. |
4. Other API use cases
Here are two common features that are not included in the previous API.
| Function | Target API | Notes |
|---|---|---|
| File download | Files | These are downloaded using the exported_file_id returned when the async option is specified in conditions such as Billing: exportBilling, etc. Please note that this is different from Harvest Files (File Entry). |
| Authentication | Auth | This API is called when authenticating on the API reference page, and is used to get an API key and token required for API call. It’s very basic is also one of the top 3 APIs for call ranking because it’s that useful. |
We hope that you have a better understanding of the long list of Soracom services at your disposal. If you don’t know what to do with the User Console, or don’t know what kind of request to send in this article, open your browser’s developer tools to see what kind of requests are being made and check out the API Reference.
If you have any problems, please consult via the support ticket from the user console.
