Common Operations on Resources¶

Fetching resource(s) SHOULD use the HTTP verb GET for request [800]¶

Resources can be fetched by sending a GET request to a service.

Responses can be further refined with the optional features as described in the below topics.

A Successful fetch of individual resources MUST return the status code 200 [800.1]¶

A server MUST respond to a successful request to fetch an individual resource or resource collection with a 200 status code response.

A server SHOULD respond to a successful request to fetch an individual resource with a resource object provided as the response document's primary data.

Here is an example of a GET request for an individual device.

GET http://example.com/devices/1 HTTP/1.1
Accept: application/json

Here is an example of the returned response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "links": {
    "self": "http://example.com/devices/1"
  },
  "data": {
    "id": "1",
    "name": "My Device"
  }
}

A successful fetch of resource collection request MUST return a 2xx status code [800.2]¶

A server SHOULD respond to a successful request to fetch a resource collection with an array of resource objects or an empty array ([]) as the response document's primary data.

Here is an example of a request that fetches a collection of devices.

GET /devices HTTP/1.1
Accept: application/json

Here is the server response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "links": {
    "self": "http://example.com/devices"
  },
  "data": [
    {
      "id": "1",
      "name": "My Device"
    }, 
    {
      "id": "2",
      "name": "Another Device"
    }
  ]
}

Here is an example of a similar response representing an empty collection.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "links": {
    "self": "http://example.com/devices"
  },
  "data": []
}

For fetching collections of resources the API has to report the following HTTP status codes:

Unsuccessful resource request MUST comply the error reporting rules [800.3]¶

If the server of the API wants to redirect the API client, the 3xx status codes SHOULD be used.

See error reporting for more details on handling reported errors of the APIs.

API MUST support fetching resource data for provided links [800.4]¶

An API MUST support fetching resource data for every URL provided as:

• a self link as part of the top-level links object
• a self link as part of a resource-level links object

A HTTP POST request SHOULD be used to create resources [801]¶

A resource can be created by sending a POST request to a URL that represents a collection of resources. The request MUST include a single resource object as primary data.

POST requests are used to create single resources on a collection endpoint. The semantic is: "please add the attached representation of a new resource to the collection resource identified by the URL".

In case your domain requires other semantics on single resources endpoint, this MAY be realized too. The meaning is best described as "please execute the given well specified command on the resource identified by the URL" and command semantic MUST be documented in API specification.

Here is an example of a POST request to create a new device.

POST /devices HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "data": {
    "name": "My Device",
    "deviceType": {
      "id": "hvac",
      "name": "HVAC device"
    },
    "dimension": {
      "width": 1.3,
      "height": 2.52,
      "depth": 0.9
    },
    "owner": "Werner Inc.",
    "tags": ["alarming", "failsafe", "redundant"]
  }
}

Creation of a given type of resource MAY be not provided by a server [801.1]¶

It is not mandatory for a sever to provide the functionality to create every type of resources. This could be for example because resources of some type are predefined or created by the server autonomously, but other reasons may exist too.

A server MAY accept an client-generated ID along with a request [801.3]¶

A server MAY accept a client-generated ID along with a request to create a resource. An ID MAY be specified, such as with an id key.

API MUST respond to successful POST creation request with 2xx success status code [801.4]¶

If the requested resource has been created successfully and the server changes the resource in any way (for example, by assigning an id), the server SHOULD return a 201 Created response and a document that contains the resource as primary data.

A server MAY return either a 201 Created status code and response document (as described above) or a 204 No Content status code with no response document. It is recommended to not return a 200 - OK status code for creation requests, because the semantic of 201 is simply better.

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 MAY return a 202 Accepted status code.

Other top-level members, such as meta, could be included in the response document.

Unsuccessful POST creation request MUST comply the error reporting rules [801.5]¶

If the server of the API wants to redirect the API client, the 3xx status codes SHOULD be used.

For errors related to the creation of resources, see error reporting for the summary of the error codes.

Updating fields of a resource SHOULD use the HTTP verb PATCH for request [802]¶

The HTTP verb PATCH is used to update specific parts of the resource objects. In contrast to the HTTP verb PUT to replace a resource, PATCH changes only a specific subset of resource fields. The set of changes is represented in a format called a patch document passed as document in the request and identified by the same media type.

Every PATCH requests SHOULD specify the partial update with JSON Merge Patch format [802.1]¶

The patch document is defined in the PATCH request according the JSON Merge Patch (see RFC 7396).

A JSON merge patch document describes changes to be made to a target JSON document using a syntax that closely mimics the document being modified. Recipients of a merge patch document determine the exact set of changes being requested by comparing the content of the provided patch against the current content of the target document.

• add property value If the provided merge patch contains members that do not appear within the target, those members are added.
• change property value If the target does contain the member, the value is replaced.
• remove or clear property value Null values in the merge patch are given special meaning to indicate the removal of existing values in the target.

Example of JSON Merge Patch¶

Here is an example of a "device" resource object that you can update.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My device",
  "createdAt": 2022-12-19T16:39:57+01:00,
  "deviceType": {
    "id": "hvac",
    "name": "HVAC device"
  },
  "dimension": {
    "width": 1.3,
    "height": 2.52,
    "depth": 0.9
  },
  "owner": "Werner Inc.",
  "tags": ["alarming", "failsafe", "redundant"]
}

Here is an example of a PATCH in which you can update the width and remove "alarming" from tags collection as well as clear owner.

PATCH /devices/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "owner": null,
  "dimension": {
    "width": 1.35
  },
  "tags": ["failsafe", "redundant"]
}

Here is the resulting resource.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My device",
  "createdAt": 2022-12-19T16:39:57+01:00,
  "deviceType": {
    "id": "hvac",
    "name": "HVAC device"
  },
  "dimension": {
    "width": 1.35,
    "height": 2.52,
    "depth": 0.9
  },
  "owner": null,
  "tags": ["failsafe", "redundant"]
}

Any PATCH request MUST be rejected on non-existing resource object [802.2]¶

The PATCH requests are not robust against non-existence of resource instances. If a new resource shall be created, the API client has to follow the rules of creating a resource.

Therefore, any PATCH request on non-existing resources is rejected with error code 404.

A PATCH request SHOULD address a single resource only [802.3]¶

The PATCH requests are applied to single resources as patching entire collection is challenging and not intuitive without a concrete domain context.

Any missing fields of resource object in PATCH document MUST NOT be altered implicitly [802.4]¶

Any or all of a resource's fields MAY be included in the resource object included in a PATCH document.

If a request does not include all of the fields for a resource, the server MUST interpret the missing fields as if they were included with their current values. The server MUST NOT interpret missing fields as null values.

Fields not included in the request should stay unmodified. For example, in above example for device, in order to remove an element from the tags array we have to include all remaining array elements.

Patching this way makes PATCH requests usually idempotent. Only constraint is the concurrent change of other fields with independent, different PATCH requests.

API MUST respond to successful PATCH update request with 2xx success status code [802.6]¶

On a successful PATCH request, the server will update parts of the resource addressed by the URL as defined by the change specified in the patch document.

Unsuccessful PATCH update request MUST comply the error reporting rules [802.7]¶

If the server of the API wants to redirect the API client, the 3xx status codes SHOULD be used.

For API client reported or server errors, see error reporting for the summary of the common error codes. These errors SHOULD comply with the common error codes.

Updating resources by replacing them MUST use the HTTP verb PUT for request [803]¶

The PUT requests are used to update entire resources. The semantic is best described as "please put the enclosed representation at the resource mentioned by the URL, replacing any existing resource.".

The PUT request operates on an existing resource. An API client can use the resource URL with a GET request to obtain the single resource object. If the resource does not exist, the rules of create a resource object apply.

The PUT request MUST include a single resource object or collection resource as primary data. All of a resource's fields SHOULD be included in the resource object included in a PUT request.

On successful PUT requests, the server will replace the entire resource addressed by the URL with the representation passed in the payload (subsequent reads will deliver the same payload, plus possibly server-generated fields like modifiedAt).

For example, the following PUT request is interpreted as a request to replace the device 1 with the given representation.

PUT /devices/1 HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "data": {
    "id": "1",
    "name": "My device",
    "deviceType": {
      "id": "hvac",
      "name": "HVAC device"
    },
    "dimension": {
      "width": 1.34,
      "height": 2.62,
      "depth": 1.1
    },
    "owner": null,
    "tags": ["failsafe"]
  }
}

PUT update request SHOULD be provided only for single resource objects [803.1]¶

It is recommended to not offer the possibility on server side to replace a resource collection at once. There is the high probability of data loss if the API client did not have the complete resource collection to create the holistic, consistent and complete collection in the PUT request.

API MUST respond to successful PUT update request with 2xx success status code [803.2]¶

Successful PUT requests return the following HTTP status codes.

Unsuccessful PUT update request MUST comply the error reporting rules [803.3]¶

If the server of the API wants to redirect the API client, the 3xx status codes SHOULD be used.

For errors related to the creation of resources, see error reporting for the summary of the common error codes. These errors SHOULD comply with the common error codes.

A replacing update with PUT SHOULD operate idempotent [803.5]¶

The update has the same intended effect on the resource, independently whether it is executed once or multiple times.

The API client MAY use conditional header information to solve concurrent update requests [803.6]¶

To prevent unnoticed concurrent updates when using PUT, the server endpoint MAY consider to support ETag together with If-Match/If-None-Match header. This offers the server the possibility to react on stricter demands that expose conflicts and prevent lost updates.

Of course this rule is only valid for optimistic locking behavior.

Deleting resources MUST use HTTP verb DELETE for request [804]¶

A resource can be deleted by sending a DELETE request to the URL that represents the resource.

DELETE /devices/1 HTTP/1.1
Accept: application/json

MUST respond to successful DELETE request with 2xx success status code [804.1]¶

The 2xx Success Status Codes MUST be used to report the API client of the API a successful deletion of the requested resource(s).

In brief the following status codes are used.

Unsuccessful DELETE Request MUST comply the error reporting rules [804.2]¶

If the server of the API wants to redirect the API client, the 3xx status codes SHOULD be used.

For errors related to the deletion of resources, see error reporting for the summary of the correct codes.

Redirect 3xx Status Codes¶

If the server of the API cannot perform the request but wants to redirect the API client to the correct endpoint, the following response code SHOULD be used.