How to make client to HTTP API on Swagger in 10 minutes

When you need to make several requests to the HTTP API, the developer usually takes his usual language / framework and quickly writes an analogue of curl in the code: HTTP request, minimal error control, query or json arguments, json body parsing with field names as strings. All this works wonderfully until the project begins to grow and several calls do not turn into several dozens, and pieces of low-level code do not begin to multiply with copy-paste. And then - a standard set of bugs, born copy-paste, which gradually begin to have time with the developer.



Swagger / OpenAPI is one of the "combines" for working with the HTTP API. This is an API description language (recently, a generator and a spec project have been merged), server and client code generators, documentation, tests — many useful pieces. Under the cat, I will show how to create an OpenAPI description and generate a client in Python using the “human” description of the API on the company's website with a few lines of code. And the better such a client is than a hand-written code.

Use the Voximplant HTTP API as a test subject.

Voximplant HTTP API was made by us more than five years ago and allows you to fully manage the cloud: create scripts for working with calls, users, rent and connect numbers, initiate calls and so on, and so on. The developer’s admin panel is entirely made on top of the API and is a good illustration of its use, if you look at the browser’s HTTP requests log.



For example, take endpoint / AddScenario , which uploads JavaScript code to the cloud. This code will be executed for incoming / outgoing calls and manage these calls (connect with each other, recognize and synthesize voice, record and so on). We wrote in the documentation that the HTTP API can be used with any verb (GET, POST, and so on), arguments can be passed url-encoded or body-encoded, and the return value is JSON with documented fields. Also, most APIs use a single authentication scheme: you can use account id, name or email as an identifier, and api key, password or temporary session id as confirmation.

')

Describe the HTTP API with Swagger

Despite the fact that the official site meets us with the specification of version 3.0, this is a snag. The generator so far can only 2.0, which we will use. Swagger supports descriptions in YAML or JSON format, and I will use YAML to reduce the amount of code. The “introductory” part of the API description fixes the version of the spec and the root URL where requests will be made:





We describe Endpoint:





We describe the authorization options. If we make a description for ourselves, then from the possible options it is enough to describe the one that we will use. For example, by account id and api key:





We describe the name and code of the script. Our server handles the parameters from url and body in the same way, but the network infrastructure is unlikely to be happy if we send a request with a dozen other kilobytes of text in the URL. Therefore, for scenario_script we write strictly the transmission through the body:





The final touch is the return value. All API return JSON:

We generate client using swagger-codegen

With the resulting API file description, you can do a lot of interesting things: generate a server, documentation, tests. We will generate a client! For example, in Python - Swagger supports dozens of combinations of programming languages ​​and frameworks. The easiest way to download the code generator is to download it as a jar-archive and run it using the pre-installed Java:





The result of the team will be a completely ready Python project with documentation in .md format, customized tests, deployments and other good stuff. Which you can immediately try to work:

Why generate a client?

The generated client is, above all, error control. You once describe your (or someone else's) HTTP API with all restrictions and objects, after which the generated code will check the correctness of the calls and usage. OpenAPI syntax allows you to specify reusable fragments, so duplicate parts are not copy-paste even in the specification.



Swagger can do many languages ​​and frameworks, so once having described the API, you will get ready-made clients for Python, Java, Ruby, PHP, Node.js, Android, iOS - the list goes on for quite a while:







For our HTTP API, we generate a Swagger description in JSON format, if you are interested in trying, then it is available here .