Introduction
API security is a hot topic these days, with more and more businesses exposing their data and services to the world via APIs. As a result, it's becoming increasingly important to have a clear and easy-to-understand definition of your API, so that clients and developers can know how to use it.
If we already have a great definition for the resources in our Web API, our clients will be excited to use it. But how do we inform them about our endpoints, models, message errors, etc.?
One way to do this is to use the OpenAPI Specification, which is a standard for defining REST APIs. There are hundreds of fantastic articles on RESTful APIs, so I will not be delving deep into that topic in this post.
Instead, this article will explore the benefits of using OpenAPI (formerly Swagger), including the ability to generate source code from your definition and distribute it among your clients.
Why is this even useful?
If you are not maintaining a live API seeing the value here might be a little more difficult. But beyond the value of it being both Human- And Machine-Readable, Helps speed up API's time to market, Language-Agnostic and more...
Ease of Use
When someone first explores OAS, he will probably wander upon their lovely online editors -
https://editor-next.swagger.io/,
https://editor.swagger.io/.
But if you don't have an OAS spec in hand this may already seem tedious. Don't worry because almost every mainstream language already has a code-to-OAS generator, here are some of my favorite examples:
Python
Common frameworks for building APIs in Python are the Django Rest Framework and Flask-RESTPLUS. Django developers can add the django-rest-swagger module via pip, whereas Flask-RESTPLUS has Swagger support built in. Both are very powerful in terms of automation, so they do not require a lot of configuration.
Javascript/Node
Applications built in Node mostly use Express or HAPI as their framework. Third-party modules called swagger-express and hapi-swagger are available for those.
If you prefer working offline, there is a nice extension for VS Code to edit your API definition called OpenAPI (Swagger) Editor (https://github.com/42Crunch/vscode-openapi).
By using this editor, you will have a GUI to edit your OAS file and you will have it edited in real-time.
And, using VS commands, you will have a list of commands that can help you add new elements to your OAS:
OAS and DevOps
In my opinion, the most important feature of OAS is the security it can provide. By making a standard API specification that is both Human - And Machine-Readable, you open the floodgates (in a good way) to the security automation of APIs. And that is precisely where the new version of BLST's open-source tool comes in. BLST's tools integrate seamlessly into CI pipelines, helping to ensure that critical API flaws do not make it to production environments.
Thanks for taking the time to read my post! If you're looking for any info about what we do at BLST check these links out:
Star our Github repo and join the discussion in our Discord channel to help us make BLST even better!
Test your API for free now at BLST!
Top comments (4)
I love OpenAPI. Ever since we switched to it in our company it made everyone's job (frontend like backend) so much simpler. At the time I wrote oa-client, a library that allowed us to replace 10K+ lines of code into less than 100.
As a contract specification it is ideal, code generation (both client and server), security specification, cloud extensions (e.g. AWS API Gateway), and input output data specifications.
We've been working with OpenAPI for a couple of years now and it was actually the basis upon which we started a code generation product which we'll be releasing info to the public about very soon
While OpenAPI is certainly useful for stable APIs and code generation, I'm not sure how this really ties into security?
OAS itself does not tie in to security, but using it with tools like cherrybomb greatly increases the efficiency of performing API security tests!