A Data resource represents a first-class data object in the world. Its properties are not computed from other resources, as are Info resources, but directly created by a system actor. A Data resource is intended to be editable by the client. It can offer the modification methods
PATCH, and it can also offer
DELETE if the resource is deletable. A Data resource often has business validation rules on the server to ensure data correctness.
The Data profile provides the required
allow headers. If the resource supports
PATCH operations, it will include the
accept-patch header with a list of acceptable patch media types. The client will need to understand these formats in order to construct a patch document to submit with a modification request. Some possible patch media types include application/json-patch+json, application/merge-patch+json, application/xml-patch+xml or application/patch-ops-error+xml.
A data resource can help clients update the resource state by providing a data schema. HTTP has no response headers that would point to the data representation’s schema, but the data resource could respond to schema
content-type requests such as
application/xml-dtd by returning schema documents. XML representations that use XML Schema should declare their
schemaLocation properties as reachable URLs.
A client uses the
GET operation to fetch the Data’s representation.
A client can use the
PUT operation to replace the data in a Data resource. However, a client cannot create (or recreate) a Data resource with the
PUT operation. The URL must point to an existing data resource.
| ||The data’s body is malformed.|
| ||The data is semantically-incorrect.|
| ||Values in the data are not accepted by business validation rules.|
If a Data resource offers the
PATCH operation, then the client can modify the Data resource using a patch document. The client must use a patch format supported by the resource (as discovered in the
accept-patch header) and construct a patch payload to submit with the
PATCH operation. The client should send a
content-type header indicating the patch format. If the resource supports more than one patch media type, it may require this header for disambiguation.
If the patch cannot be applied successfully, the resource returns
409 Conflict. The client should re-fetch the data resource and rebuild the patch payload. If the patch is applicable, but the resulting data values violate business validation rules, the resource sends back
| ||The patch’s syntax is malformed JSON or XML.|
| ||The patch data is semantically-incorrect. Check the patch format specification for errors in the body.|
| ||The patch cannot be applied successfully because the state of the resource is not in the right shape to accept the patch. Consider using the Entity mixin to help clients identify missed changes to the resource.|
| ||Patch can be applied successfully, but the updated values in the data are not accepted by business validation rules.|
| || |
A client can remove a Data resource by sending a
DELETE request. If the resource cannot be deleted due to business reasons, the server will return
403 Forbidden status.
The Entity mixin gives Data fetch cacheability and safe modification.
The Async mixin provides a client with “fire-and-forget” data modifications.
The Representation mixin allows the client to receive the modified data representation in the
HTTP Extensions for WebDAV: RFC 4918
- 422 Unprocessable Entity: section 11.2
XML Patch Operations Framework: RFC 5261
PATCH Method for HTTP: RFC 5789
accept-patch: section 4.1
Additional HTTP Status Codes: RFC 6585
- 428 Precondition Required: section 3
JSON Patch: RFC 6902
HTTP/1.1 Semantics and Content: RFC 7231
- 200 OK: section 6.3.1
- 204 No Content: section 6.3.5
- 403 Forbidden: section 6.5.3
- 409 Conflict: section 6.5.8
XML Patch: RFC 7351
JSON Merge Patch: RFC 7386
© 2019-2023 Matt Bishop
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.