tutorial

Creating API clients using OpenAPI Tools

How to quickly create a Qovery API client in your language
type: tutorialtechnology: qovery

While releasing the latest major update of Qovery, we realized that we need to open our API to our users in order to make them able to build integrations and customizations they need in their development workflows. This month, we launched a BETA version of the Qovery V2 platform, and alongside this, we made our beta API open and ready to play with and experiment.

Integration

To integrate with the new API, one has a choice of reading the documentation and doing all the necessary plumbing by himself. However, at Qovery, we value developer experience, so we decided to make this process easier and more streamlined.

Generating API client code

Our API specification is made in a way that makes it very easy to generate API clients in any of the many supported languages. We also prepared a script to make this process seamless - all you need to do is to clone our open API repository and run one command to generate the newest client version.

Steps

  1. Clone the repository

    $ git clone https://github.com/Qovery/qovery-openapi-spec.git
    $ cd qovery-openapi-spec

  2. Generate the client code

    $ QOVERY_CLIENT_LANGUAGE=go npm run generate

    where: $QOVERY_CLIENT_LANGUAGE is the language of your choice.

  3. List the generated files

    $ ls out/client

    This folder contains all the files necessary to interact with Qovery API, as well as its documentation. To use it in your project, you can create a repository to store the client files and then import them as a dependency in your project. This part is highly dependant on the language and technology you are using, so it's not covered in this post.

Under the hood

The npm run generate -- $LANGUAGE command under the hood uses the open-api-generator and a Open API specification created to define Qovery API. You can see the specification after cloning our open api repository and running npm run build in _build/openapi.yaml file.

The clients are generated using the open-api-generator and the specification file - _build/openapi.yaml.

Example

As an example of generated API client, let's use the Qovery CLI. The command-line interface of Qovery is using a Go API Client that was generated following the steps from this article. After generating the client, we simply published the out/client folder as a Git Repository and then simply imported the code in the CLI application as a dependency:

package utils


import (
    "github.com/qovery/qovery-client-go"
)

This allowed us to use the generated client code to interact with Qovery API very easily:

token, err := GetAccessToken()
if err != nil {
    return err
}


auth := context.WithValue(context.Background(), qovery.ContextAccessToken, string(token))
client := qovery.NewAPIClient(qovery.NewConfiguration())


organizations, res, err := client.OrganizationMainCallsApi.ListOrganization(auth).Execute()
if err != nil {
    return err
}
if res.StatusCode >= 400 {
    return errors.New("Received " + res.Status + " response while listing organizations. ")
}

Summary

Qovery Open API specification allows creating Qovery API stubs extremely quickly. At Qovery, we officially support only Golang Client, but if you use a different language, you can generate your own client in a matter of seconds following the steps of this article.