Document position on updating singleton resources

snyk / sweater-comb

API linting rules

Other

22 stars 8 forks source link

Document position on updating singleton resources #71

Open cmars opened 2 years ago

cmars commented 2 years ago

When updating singleton resources (there can be only one, like the Highlander), .data.id should be optional in the PATCH request body. This is a decision to depart from JSON API, which has this as an unconditional MUST.

cmars commented 2 years ago

This could be linted with a type annotation indicating it's a singleton.

cmars commented 2 years ago

Proposal:

When the type of .data under GET /resource is an object, the resource is considered to be a singleton.
Singletons are eternal. They always have been and always will be. (Until they're sunset!)
- POST and DELETE operations are not allowed.
GET is required. PATCH is optional. In both, .data is an object, not an array.
.data.id is not specified. The type is its identity, because it is a singleton.

cmars commented 2 years ago

@mrded I've spec'd this out to Optic in #195. They may have advice here on our WIP #192.