NAO Cloud allows resources of a given type to be created and allows some existing resources to be modified or deleted. A request either succeeds or fails atomically (in a single “transaction”). No partial updates are allowed.

Creating Resources

A resource can be created by sending a POST request to a URL that represents a collection of resources. The request should include a single resource object as primary data. NAO Cloud does not accept a client-generated ID along with a request to create a resource.

For instance, a new site might be created with the following request:

POST /api/v2/sites HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: UNyCernxjUHR18Rx1Qy7XGDyAdVksqDf8w

{
  "site": {
    "name": "My lovely site",
    "longitude": 1.3871262673941822,
    "latitude": 43.56439230039133
  }
}

If the requested resource has been created successfully, the server will return a 201 Created status code, along with the resource details in the JSON body. An auto-assigned id will always be returned in the JSON body, which enables the client to interact with the individual resource later on.

If a request to create a resource has been accepted for processing, but the processing has not been completed by the time the server responds, the server will return a 202 Accepted status code. A job resource id will also be returned, enabling the client to monitor the processing progress.

In case of error in the request, a 422 Unprocessable Entity is returned.

Updating Resources

A resource can be updated by sending a PUT request to the resource URL. Any or all of a resource attributes can be included in the resource object included in the request. If a request does not include all of the resource attributes, the server will interpret the missing attributes as if they were included with their current values. The server will NOT interpret missing attributes as null values.

For example, the following PUT request is interpreted as a request to update only the name of a site:

PUT /api/v2/sites/1 HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: UNyCernxjUHR18Rx1Qy7XGDyAdVksqDf8w

{
  "site": {
    "name": "A new name"
  }
}

The server will return a 200 OK status code if an update is successful. The response document will include a representation of the updated resource(s) as if a GET request had been made to the request URL.

In case of errors, a 404 Not Found or a 422 Unprocessable Entity might be returned.

Deleting Resources

An individual resource can be deleted by making a DELETE request to the resource’s URL:

DELETE /api/v2/sites/1 HTTP/1.1
Authorization: UNyCernxjUHR18Rx1Qy7XGDyAdVksqDf8w

The server will return a 204 No Content status code if a deletion request is successful and no content is returned. A 404 Not Found might be returned if the resource does not exist.