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.