Updating Resources

Several of the Oracle IoT Cloud Service REST APIs are used for creating, updating, or deleting different resources. Some of the different conventions and approaches used by these APIs are discussed below.

In general, deletion, where supported, is simply a matter of sending a DELETE request to the resource to be deleted. And where resource creation is possible, the POST HTTP method is used to create that resource in all cases.

Resource Creation

Resource creation is always done via a POST request. A successful response to such a request may return a 201 Created if the resource was created immediately, or may return a 202 Accepted if the resource will be created asynchronously. In either case, a resource is created that represents the pending operation that can be subsequently queried to inspect the state of that creation request. One of the standard errors is returned if resource creation is not possible, perhaps due to a bad request.

The documentation for each Oracle IoT Cloud Service REST API that supports resource creation defines, in detail, the expected request body (if needed) and the appropriate response and error codes.

Partial Resource Update (PATCH)

The IoT Cloud Service supports partial updates to resources via the pseudo-HTTP method PATCH. In practice, many parts of a network infrastructure don't support custom HTTP methods, so PATCH is actually handled either with the PATCH http method, or by sending a POST with the header X-HTTP-Method-Override: PATCH. This instructs the cloud service to patch the resource instead of create a new one.

Patching is a relatively simple process. For example, to update an endpoint's description, one could issue the following HTTP Request:

POST http://MySmartHome-MyCompany.iot.us1.oraclecloud.com/iot/api/endpoints/101 -H "X-HTTP-Method-Override: PATCH"
Content-Type: application/json
Accept: application/json

{"description": "Home Office Lock"
}

The resulting response would be similar to the following:

{
    "links": [
        {
            "rel": "canonical",
            "href":http://.../iot/api/v1/endpoints/100
        }
    ]
}