With innovative API technologies emerging in recent years, there are more options to choose from when deciding on the right approach to building an API. When deciding on the route you’ll take, API standards should be an important consideration.
It can be tricky to keep up with API standards using the latest approaches. Depending on your requirements for discoverability, documentation and security, some of these technologies may simply be too nascent.
Types of API to Choose Between
Over the years, developers have become used to working with a growing variety of API standards. In the late 1990s, the SOAP protocol emerged; then in the early 2000s, REST. The vast majority of public APIs in the world today continue to be either SOAP or REST APIs.
But since 2015, we’ve seen more and more APIs following two newer standards: gRPC and GraphQL. Asynchronous APIs are also increasingly common following other protocols such as AMQP, MQTT and Kafka.
When deciding on the best approach for a new API, giving due consideration to standards for documentation, discovery and security is essential.
Don’t Overlook Documentation & Discovery Standards
No one will use your API if you don’t document it well, which is why there are standards emerging for making sure APIs are both well-documented and discoverable.
For synchronous APIs, OpenAPI (previously Swagger) is the most widely adopted standard. Tools such as Swagger Codegen are a real benefit, as you can automatically generate an SDK for your APIs that developers can easily consume.
When it comes to the more emergent field of asynchronous APIs, things are still somewhat in flux, but we’re starting to see the industry settle around AsyncAPI combined with agreed payload formats such as CloudEvents.
As well as documenting your APIs, it’s equally important to make them easily discoverable. In certain cases, developers will naturally go looking for an API — Twitter’s public API, for example. But, more often than not, APIs must be advertised, and even internal teams should consider providing their service to other teams within their organization via agreed contracts.
We’re beginning to see tooling, such as Spotify’s Backstage, designed for this very purpose of managing available services and making them easy to discover.
Security Standards are Clearer for Synchronous APIs
APIs can be a security vulnerability, so staying abreast of best practices to make sure your APIs are secure is obviously essential. When it comes to building a synchronous API there’s no shortage of detailed guidance. OWASP publishes best practices for security relating to synchronous APIs:
There are commonalities and differences between these sets of recognized best practices. To give just one example, input validation is a high-level best practice for different APIs, but the specifics vary depending on the particular API technology.
By contrast, we’ve yet to see comparable levels of guidance for security when it comes to publicly available asynchronous APIs. So while they’re gaining popularity, asynchronous APIs might not be your best option where security is especially important.
Balance Innovation Against Following API Standards
Being at the cutting edge of innovation always presents an exciting and valuable opportunity for experimentation. But for projects where keeping to API standards really matters, it’s worth recognizing that newer API technologies lag behind the established options when it comes to API standards. To be sure that your API is fit for purpose in terms of documentation, discoverability and security, sometimes the smart choice is to go with what’s tried and tested.
