Cellular IoT - API First
At EMnify, we develop our cellular IoT platform features using an 'API-first' approach. This means that we design and implement our APIs before any other functionality and consider our API as one of the most important components of our platform. Most other features and applications we develop, such as our GUI management platform, are all built around our APIs.
With using the REST architectural style and OpenAPI / Swagger tools we make it very simple for our customers to use and develop based on our API. Customers can even test the API within the documentation itself.
Our users regularly leverage our open platform via API to:
- Activate and Pause SIM card contract when devices are going to or coming from the field
- Gain insights on how and where their devices with EMnify IoT SIMs are operating
- Integrate connectivity information into their IoT applications
- Develop monitoring and/or alerting functionalities for their devices
- Conduct highly granular device management with custom or non-trivial logic
- Resell connectivity to clients through quota or prepaid management functionalities
- Build their own graphical user interfaces
Since our APIs enable such crucial functionality, providing comprehensive and simple to digest API documentation is a mission-critical task. As there is no official specification for REST APIs (only their components), we use Swagger to standardize how our APIs are designed and documented.
What is Swagger?
Swagger is a specification for REST APIs which has been in open development since 2010. The specification is written in JSON or YAML to describe the resources, parameters, patterns and methods of a REST API. The Swagger specification enforces documentation conventions to ensure that API features are described in a standardized and structured way.
The benefits using Swagger for documentation are the large amount of open source tooling, community support and pre-existing documentation. As Swagger has grown in popularity, so have the number of open source and third-party applications and utilities available, providing a wide range of resources from generating documentation to code templating and scaffolding client code or server stubs. The Swagger spec itself is a language-agnostic way to describe APIs while remaining readable by both human and machine. Using this well-defined way of describing the API with the available tools and utilities can generate impressive results.
Docs as Code
At EMnify, we document our APIs in a Swagger Specification file which is embedded in our documentation pages during the build and deploy pipeline. When browsing our Swagger pages, the Swagger UI framework reads the spec file and the documentation is rendered as the page loads. The Swagger UI generates HTML components for each entrypoint and presents API features in a logical way that can be browsed and consumed easily by the user. Each of our API entrypoints is documented in a way that gives an indication of the types of responses that this entrypoint may return, along with generic conventions. We have the option to display an example value that this API entrypoint would return.
We are leveraging Swagger’s schema descriptions extensively to fully model the data types that are used by our APIs. Schemas are reusable components defined for common objects and data types that appear in multiple places in our systems and documentation. By referring to common schemas, we can keep our Swagger specification DRY while improving the accuracy of our documentation.
Users browsing the documentation can make use of one of the most impressive features of the Swagger UI framework and directly make calls against the live system API. By generating an application token from within the EMnify User Interface, users can gain programmatic access to the API in the documentation itself and make HTTP requests against real data.
Generating Client Code
Swagger Codegen is an official command line tool which allows users to read the description file and generates client and server code directly from the design. In the screencast below, we are reading the EMnify Swagger file and generating typescript client code for the EMnify API (into the gen-angular directory, in this case). A look through the open source integrations shows the extensive range of options on-hand for parsing, validating, generating client and server stubs in 32+ languages.With these considerations, it is easy to see why we have chosen to leverage Swagger’s format and modern, lightweight tooling, to generate detailed, verifiable and insightful documentation so that our users can get the most out of our APIs.
Notes on OAS
The Swagger specification and open source utilities have achieved considerable traction in developer communities over the years and received widespread refinement and adoption. The specification itself was formally renamed to the OpenAPI Specification (OAS) in 2016 and maintenance was handed over to the Linux Foundation. This marks the maturity of the specification as a description language and underscores that the format is becoming a de-facto standard for documenting REST APIs.
Our team of dedicated IoT/M2M experts is available to discuss your requirements and help find the best solution for your IoT project. To find out more, you can contact us at mail@emnify.com or call +49-30-5557-33333.
What can your connectivity provider do for your device security?
Check out our Guide for Cellular IoT Securityfor 25+ best practices
to ensure a secure IoT solutionfor your business.
