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.

Before


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.

After


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.

Blog

À lire également

Clever Cloud structures itself to support its organic growth

In 2023, Clever Cloud has once again made great strides, with a significant increase in its turnover. Having recently passed the 60-strong mark, the company is welcoming new profiles to support its development, and is expanding its Management Committee.
Company Press

Clever Cloud and CISPE: a strategic commitment to the European Cloud

Continuing its commitment to digital sovereignty, Clever Cloud is proud to announce its participation in CISPE (Cloud Infrastructure Services Providers in Europe association).
Company

Clever Cloud opens a new Gravelines HDS region

Clever Cloud opens a new Gravelines Health data Hosting region to have redundancy on those sensitive datas.
Company