DEV Community

Cover image for OAS is the most critical tool for API Developers
Daniel for BLST

Posted on • Updated on

OAS is the most critical tool for API Developers

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.

Image description

And, using VS commands, you will have a list of commands that can help you add new elements to your OAS:

Image description

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)

Collapse
 
ninofiliu profile image
Nino Filiu

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.

Collapse
 
rolfstreefkerk profile image
Rolf Streefkerk

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

Collapse
 
fjones profile image
FJones

While OpenAPI is certainly useful for stable APIs and code generation, I'm not sure how this really ties into security?

Collapse
 
chainguns profile image
Daniel

OAS itself does not tie in to security, but using it with tools like cherrybomb greatly increases the efficiency of performing API security tests!