API-documentation.md

 ![api](uploads/ff1503057facb703a1ece19de0fb6335/api.png)
 # Quick start
 
-Start Page : https://operations-portal.egi.eu/api-documentation
+[Start Page]( https://operations-portal.egi.eu/api-documentation) - You must authenticate with your EGI account.
+
+If you don't have a token yet, click the button "Ask for token". Else, your token is displayed on the page.
 
-One you are on this page you should ask for a token  ...
 # How to use the token ?
 
-Donner qq exemples de requêtes avec le header
+The API is stateless, which means you have to set the token in the header of every request to use the API properly.
+The token must be set to the "X-API-Key" parameter in the HTTP header.
+ 
+ With the [curl](https://curl.se/) tool, the command below shows how to set the token on a GET request.
+ 
+```curl -X GET "https://operations-portal.egi.eu/api/endpoint" -H  "X-API-Key: your-token"```
 
 # How to use the API UI page ?
 
-Expliquer avec des copies d'écran ? 
+If you have a valid token, you can request the API from anywhere, including it's [start page]( https://operations-portal.egi.eu/api-documentation), which provides an user interface, and demo features.
\ No newline at end of file
+
+To do this, click the "Authorize" button, and set your token value in the prompt. In this way your token will be automatically set in the header (X-API-Key) for all your requests on this page. 
+You can now request every endpoint of the API with a friendly user interface. 
+
+The image below shows an example of one endpoint.
+
+TODO image
+
+Send your request by clicking "Try it" on the route you want to request, set the appropriate parameters, and click "Execute".
+
+
+As soon as the response is back, the API user interface will display :
+ - The response's HTTP status and content (in case of error the API usually returns a helper message specifying whether it's a request problem or a server failure).
+ - TODO img
+ - The request URL matching your parameters and an re-usable Curl command line to request this URL from anywhere (see below).
+ - TODO insert image
\ No newline at end of file