October 6, 2018

API Overview

  API Reference

     

The NuevoCloud API is organized around REST:

  • HTTP verbs (GET, POST, DELETE, etc) indicate the operation to perform
  • HTTP response codes are used to indicate API errors
  • HTTP Authentication is used to control access to the API
  • JSON is returned by all API repsonses

Generate a new API key

API keys can be added to your account from your API Settings. Keys can have access to your entire account (all zones, your profile, billing data, etc) or be restricted to a single zone.

API keys should be kept secret. Never share your secret API keys with others or expose your keys in any public website's client-side code.


Authentication

Authentication is performed using HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

$ curl https://api.nuevocloud.com/1.0/zones -u nc_apikey:

Curl uses -u to pass basic auth credentials. Including a colon after the API key prevents curl from prompting for a password.

If you need to authenticate via bearer auth (for a cross-origin request), use -H "Authorization: Bearer nc_apikey" instead of -u nc_apikey:.

All API requests must be sent over HTTPS. Requests sent over HTTP and unauthenticated requests will fail.


Errors

NuevoCloud uses standard HTTP response codes to indicate success or failure. In general, 2xx codes indicate success, 4xx codes indicate a failed request, and 5xx errors indicate an error with the API server.

200 - OK The request was successful
201 - Created The resource was created
400 - Bad Request The request was missing a parameter or contained invalid parameters
401 - Unauthorized API key is invalid or does not have adequate permissions to complete the request
404 - Not Found The request path does not exist
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff.
500 - Internal Server Error Rare. Something went wrong with NuevoCloud's API server

Atomicity

All API operations are atomic. In other words, a single request specifying multiple changes to a zone will only succeed if all of the operations are successfully applied. If one of the changes fails, no changes are made.


Dates and Times

NuevoCloud uses ISO 8601 for all dates and times in responses. Dates are adjusted to the time zone specified in your account profile.


Strings and Array Handling

NuevoCloud returns null for all empty string values. Requests may use a null or empty string (i.e. "") to set a string to an empty value. However required fields cannot be set to an empty value.

NuevoCloud always returns an emtpy array (i.e. [ ]) when an array field does not contain a value.

A shortened syntax is supported for working with arrays. Requests using an array with a single value may use the value by itself.


Zone Identification

Many of the API endpoints use a zone identifier in the path. For example, in this request www.example.com is the zone identifier.

$ curl https://api.nuevocloud.com/1.0/zones/www.example.com/cache -u nc_apikey:

The API supports using the zone domain, any zone alias, or the zone ID as the zone identifier.