Updating our API doc

Hi there, I am Corentin Cailleaud, a second year student at Nantes. It has been already a month since I am in internship here at Clever Cloud. My first mission was to complete the API documentation and this job is now over. Let's have a look.

The Clever Cloud API is a tool that allows you to manage your account and your products. In order to help you using this API, I have updated the documentation, available here. Most of endpoints are now delivered with input and output models. Let's see what it means and why using the API is now easier !

How is defined our API documentation ?

Our API documentation is defined by a Swagger file. Swagger is the world's most popular framework for APIs. It helps us describing our API and it gives you a good interface to get started with this tool.

Let's take an example : you want to create a new application.

  • First you have to find the endpoint in the list. You can use resource's name to find it easily. Here we want an endpoint about application so let's find "POST /self/applications" in the "applications" list.

  • Then, you have to click on the endpoint to know the input model you have to give.

If you are logged in, you can click on the "Try it out!" button to try your request !

Restlet Studio FTW

I used Restlet Studio to modify this file as it was easier than updating the Swagger file directly from a text editor. Indeed, Restlet Studio allows you to create representations with few clicks. That's a very cool tool, here is a link to their Getting Started.

Why this update

Before this update, you could not know everything about an endpoint, there was kind of a fog of war. When you clicked on the endpoint, you could not know what to give in input.


Now, the weather is clear, all those informations are available ! You can even click on the model and it automatically goes in the box, where you can modify it.


The goal of this update is to be able to generate API client whenever the API is updated thanks to swagger-codegen. This tool can generate, from a Swagger definition, API client in different languages using different libraries. When this feature is available, your clients will be automatically updated when a new version of the API will be released.


À lire également

Materia KV: our easy-to-use serverless key-value database is available to all

Clever Cloud was born out of a desire to make life easier for developers, by providing them automation tools and interfaces, so that they can concentrate on their applications and sites.

Clever Cloud and Vates: Two French champions join forces to create comprehensive and autonomous cloud solutions

Nantes and Grenoble, May 23, 2024 - Clever Cloud and Vates are announcing today a partnership aimed at strengthening the strategic autonomy of the cloud in France and Europe.

The Values and Policies of Personal Information Chair at Institut Mines-Télécom welcomes Clever Cloud among its sponsors

The Institut Mines-Télécom's Values and Policies of Personal Information (VP-IP) Chair conducts research into the issues surrounding the processing of personal data, digital identities and sovereignty, in a context of European regulation.