Learning a new system API may feel like a daunting task. As a network engineer you may feel unsure about how to begin. Fortunately, the way to learn any API‑based system – whether a controller product, a cloud system, or even a device API – follows the same set of steps. In this post, I guide you through the initial steps and highlight key aspects to note as you are learning to use a new API. You may be using commercial products and open source projects; for convenience, here the term product refers to both. This post focuses on documentation, client libraries, and API authentication.
Documentation
The first step is to locate the API documentation, and the first item to look for there is a Quick Start. It’s a form of documentation meant to specify the minimum steps required to perform your first interaction with the API. In effect it’s a “hello, world” program that, while not necessarily accomplishing anything actually useful, serves to confirm that you can interact successfully with the API.
A general caveat is to keep an eye out for version‑specific information in the documentation. Some examples might rely on features of the API that aren’t necessarily available in your version.
Documentation is generally provided in one of three forms.
- Built into the product – For most modern products, API documentation is built into the product and auto‑generated using the OpenAPI specification, also known as a Swagger spec. When a product offers its API docs in this matter, you can usually try out the API functions using a web browser interface. If you are in the process of evaluating a product and the documentation is provided this way, you need access to a demo system so you can explore the features of the API interactively.The benefit of the built‑in approach is that when the API documentation is automatically generated from the code, it matches the product version you are using. The downside is that the documentation can be sparse and unhelpful depending on how thoroughly the developers annotate their code.
If the product makes the OpenAPI spec file available as a download (typically in JSON or YAML format), you can use it with other OpenAPI ecosystem tools such as language‑specific client generators (see Client Libraries).
- Interactive web pages on a website – Some products provide documentation on a website, either behind a login page or open to the public. A benefit of this approach is that the documentation is usually searchable across versions. Good documentation contains version‑specific notes, for example when new features are added or deprecated. When planning an upgrade, review the release notes (README, CHANGELOG, etc.) in the same way as for any software upgrade.
- Static docs – These include PDFs, READMEs, and wikis. Unfortunately, this form of documentation is often out of date or incomplete because it requires the product development team to take on a separate workflow with its own tools (word processor, publishing system, and so on). If you are presented with this form of documentation, consider requesting time with the product API subject matter experts to get their assessment as to the quality and maintenance of these documents.
Client Libraries
A client library is software intended to make interacting with an API easier. Client libraries are incorporated into programs, which makes them language‑specific – for example, the vendor might provide a client library in Python but not Ruby or Perl. You may find client libraries that are not formally affiliated with the product, but loosely associated as part of the development team’s community efforts. Community‑supported client libraries are usually provided on a best‑effort basis and not officially supported by the vendor.
Ideally you can want to use a client library provided by the vendor, with the presumption the vendor is keeping the library up to date with product changes and providing support (free or paid). Most of the time client libraries are open source and publicly available in repos like GitHub. Take some time to review the issues list at the repo for known problems, feature requests, and questions. This can give you a sense of how good the library is and how well the maintainers interact with users.
If the product provides an OpenAPI specification for download, you can also use software such as openapi-generator to generate a client based on your language of choice. There are pros and cons to using a client generator, but when you are first getting started with an API, a code generator is a great way to quickly see how the API works.
As an alternative to a client library, a vendor might offer a Postman collection. Postman is a free API‑development tool. A Postman collection is a packaged set of API calls that you can use via the Postman point-and-click user interface. Vendors often provide a Postman collection as part of their documentation or API software development kit (SDK) so that you can interact with the API without writing code. The collection serves more as a learning tool than as software you can incorporate into your own programs. That said, you can use Postman to generate code snippets in different programming languages, an effective means of quickly creating your own client libraries.
Authentication
There are two general methodologies for API authentication: login credentials and tokens. With login credentials, you use the same username and password as when accessing the product in other ways (for example, in a browser). If you are using a network‑device API, you are most likely using this method since your login credentials typically tie back to an Authentication, Authorization, and Accounting (AAA) system which performs device authentication and command authorization.
A token, by comparison, appears to you as a random set of characters. Some APIs require you to generate a token based on your login credentials before using the API, which makes authentication a two‑step process. Some APIs allow (or require) you to first generate a token using a system set up by the vendor, expose the token once so you can record it, but then never show you the token again; in this case you must keep it stored in a safe place for later use. Many APIs use the industry‑token system called JSON Web Token, which is defined in RFC 7519.
Another aspect to keep in mind is tokens may have an expiration time, meaning you have to remember to generate a new token before the current one expires or risk being locked out. As an example, an API might require you to generate a token based on your login credentials that is valid for an hour. If your program potentially runs for longer than an hour you need to build in a function for refreshing the token. Some systems require your program to provide your login credentials for the new token, while others have a mechanism for refreshing the token without requiring login credentials again.
Sometimes credentials are presented as part of a request to the API, most often in the HTTP Authorization request header. But there is no one-size-fits-all answer, and the mechanics can become complicated based on whether the system is also using authentication protocols such as Auth 2.0, OpenID Connect, and SAML2. If a client library is available, it makes sense to use it because it usually hides the complexity of the authentication process, requiring you (the developer) simply to provide login credentials or a token.
Conclusion
When you start the process of learning a new API, begin by finding the documentation and executing the quick‑start process to confirm you can interact with the API. If the vendor provides a client library package, use it at first, even if it does not exactly meet your needs, as a way to learn how the API behaves and to examine the code to understand the underlying mechanics. With that knowledge you can decide whether to develop your own client library or make changes to the existing one. You also need to understand the AAA mechanism, because the way the API requires authentication information to be encoded can impact the structure of your program, especially if the program runs for longer than the usual token validity period. Always take advantage of Postman collections when they are available. These collections act as an independent mechanism to validate the API without you having to write code. You can use collections to learn the API behavior and generate code snippets that you can incorporate into your program.