Data Profile

Profile: <http://level3.rest/profiles/data>

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 PUT and PATCH, and it can also offer DELETE. A Data resource often has business validation rules on the server to ensure data correctness.

Discovery

The Data profile provides the required Profile and 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.

Schema Discovery

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/ld+json, application/schema+json, or application/xml-dtd by returning schema documents. XML representations that use XML Schema should declare their schemaLocation properties as reachable URLs.

Fetch Data

A client uses the GET operation to fetch the Data’s representation.

Replace Data

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.

Rejections
Status Code Explanation
400 Bad Request The data’s syntax is malformed.
409 Conflict Values in the data are not accepted by business validation rules.
422 Unprocessable Entity The data is semantically-incorrect.

Modify Data

A client can use the PATCH operation to modify portions of the data in a Data resource. 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 422 Unprocessable Entity.

Rejections
Status Code Explanation
400 Bad Request The patch’s syntax is malformed.
409 Conflict Patch can be applied successfully, but the updated values in the data are not accepted by business validation rules.
422 Unprocessable Entity The patch data is semantically-incorrect.
428 Precondition Failed Content-Type request header required.

Mixins

Entity Mixin

The Entity mixin gives Data fetch cacheability and safe modification.

Async Mixin

The Async mixin provides a client with “fire-and-forget” data modifications.

Representation Mixin

The Representation mixin allows the client to receive the modified data representation in the PUT or PATCH response.

Specifications

HTTP Extensions for WebDAV: RFC 4918

XML Patch Operations Framework: RFC 5261

PATCH Method for HTTP: RFC 5789

Additional HTTP Status Codes: RFC 6585

JSON Patch: RFC 6902

HTTP/1.1 Semantics and Content: RFC 7231

XML Patch: RFC 7351

JSON Merge Patch: RFC 7386


Copyright © 2019 Matt Bishop
Creative Commons Licence
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.