Updating a single attribute

1

Hi,

This is hopefully a straightforward question…

We’re designing a set of APIs, following JSONAPI as closely as possible. We’ve a requirement to update a single attribute of a resource (its status). It will not be allowed to update anything else in the resource.

What is best practice here? I can immediately think of at least a couple of options:-

  1. PATCH /thing/12345
    With a JSONAPI payload like this:-
  {
    "data": {
      "type": "thing",
      "id": "12345",
      "attributes": {
        "status": "open"
      }
    }
  }

Attempts to update other attributes will be rejected with 400 Bad Request or 403 Forbidden.

  1. POST/PATCH /thing/12345?status=open
    (no payload)

Option (1) is clearly JSONAPI-compliant but will imply to consumers that other attributes can also be updated.
We’re not sure how to document what can and can’t be updated (using Swagger).

Option (2) seems much more lightweight but isn’t very JSONAPI-esque.

Comments welcomed,

J.

2

Hi J,

Short answer - Use hypermedia to return a link with appropriate vocabulary defined where the message and method are known.

Longer answer, check out my guidelines on designing hypermedia APIs and then you can get away from some of these more nuanced but unnecessary design conversations. An update like that shouldn’t be managed by an external caller, because that caller will have to know too much about the internal state and implementation of your service, it’s better to define a vocabulary which contains a link with rel “open-thing” with the method and message already templated within the spec. This way you never have to worry about managing enumerations with clients, or having clients send bogus data.

Good luck, hope it helps!

3

Hi Michael,

Thank you for the reply.

I can appreciate the theoretic benefits of purely hypermedia-driven APIs, but I’m of the opinion that the added complexity, particularly on the client side, outweighs these benefits.

From discussions here, we’ve decided to go with my option 1 above as it will enable us to update other attributes, if the requirement ever arises, and gets us past any criticisms of not being aligned to the JSONAPI spec.

J.

4

I understand you’ve made a decision, and reading between the lines it seems like it was informed. APIs are a spectrum, and hypermedia APIs are not the solution to every problem in the space.

I would argue the ‘boogieman’ effect is in play when trying to estimate the relative difference in difficulty in developing a hypermedia client as the unknown is a powerful force multiplier. You can’t ever release a new version of your API, you only get one crack at designing the interface and interaction.

The final point I’ll make is the value of a standard is in it’s compliance and interoperability. There isn’t much value in being a JSON:API inspired API, when I have created a client which is JSON:API compliant. The inspired design is a snowflake, and while it may be familiar, it requires the same additional effort to consume.