Getting Started ==================== API v1 Introduction ```````````````````` Welcome, this is the E2E Networks API documentation. A guide to how you can use, interact with the E2E Networks API. You can use the E2E Networks API to programmatically manage compute nodes and resources on E2E Cloud using conventional HTTP requests. The API endpoints are easy to use and are highly responsive, making it simple and effective to fetch information and to execute actions. Various actions — like creating, deleting nodes, enabling backups, etc. — that are generally performed using the MyAccount portal can be performed using the API; enabling you to script actions to execute them dynamically and automatically, as your situations demand. This API documentation starts with an overview of the implementation and then proceeds with the detailed information and example uses of various endpoints. Requests ```````````````````` .. list-table:: :widths: 25 25 :header-rows: 1 * - Method - Usage * - GET - | GET method can be used to get information regarding nodes, environment, | and your account; for example, retrieving node list or getting information | on a particular node. | GET method returns information in JSON format. The attributes available in | the JSON file can be used to create any additional requests. | All the requests made using GET method get information and are read-only; | and, they do not perform any action on the objects you are querying. * - DELETE - | DELETE method can be used to terminate, remove, or to delete a resource | in your MyAccount. This request will remove the particular object if found | in your MyAccount. If not found, the request returns the message that the | object was not found. That is, you do not have to query that whether an object | is available before using a DELETE method; and, regardless of the availability, | the final state after executing a successful request will be the same. * - PUT - | PUT method can be used to update information regarding a resource or object | available in your MyAccount. | PUT method updates the information of the resource regardless of the existing | values; and, requests made | using the PUT method will not check the existing | attributes of the resource. * - POST - | POST method can be used to create a new resource or object or in your MyAccount; | for example, creating new nodes, etc. | A request using POST method contains all the necessary attributes required | to create a new resource or object. Http Status Code ````````````````` Along responding to the HTTP methods, the API also returns standard HTTP statuses and error codes. If there is a problem with any request, the HTTP status will show the error code and the body of the response will have more details regarding the issue encountered. Below are the common HTTP status codes and their interpretation: * 200 - the request fulfilled successfully and no error occurred. * 400 - the status codes in the 400 series indicate some sort of problem with the request: a malformed request, unauthorized attempt, authentication failure, etc. * 500 - the status codes in the 500 series indicate a server-side problem, typically some issue with the E2E Networks API itself. And that the request cannot be fulfilled. **EXAMPLE ERROR RESPONSE** .. code-block:: guess HTTP/1.1 403 Forbidden { "id": "forbidden", "message": "You do not have access for the attempted action." } Rate Limit ````````````````` There is a rate limit on the number of API requests you can make, which is 5000 requests per hour per OAuth Token. Information regarding rate limiting is available in the response headers of the requests. Below are the headers * RateLimit-Limit: The number of API requests that are allowed per hour. * RateLimit-Remaining: The number of remaining API requests before reaching the request limit. Information regarding the request limit expiry is available below. * RateLimit-Reset: This shows the time by when the oldest request expires and is represented in Unix Epoch time. In general, you can make additional requests as long as RateLimit-Remaining remains above zero. The requests are not counted per hour and neither the RateLimit-Remaining is reset on an hourly basis; instead, each request has its own expiry time. So, each request expires exactly after one hour; and, accordingly the count reflects on RateLimit-Remaining. Now the question is: as each request has its own expiry time, what exactly RateLimit-Reset represents? RateLimit-Reset represents the expiry time of the oldest request made. Once that expiry time is over, the RateLimit-Reset value moves to the next oldest request. When the RateLimit-Remaining value is zero, the requests made will return the error code 429. You can make successful requests again when RateLimit-Remaining value moves above zero; that is, as more requests expire. **Sample Rate Limit Headers** .. code-block:: guess . . . RateLimit-Limit: 1200 RateLimit-Remaining: 1193 RateLimit-Reset: 1402425459 . . . **Sample Rate Exceeded Response** .. code-block:: html 429 Too Many Requests { id: "too_many_requests", message: "API Rate limit exceeded." }