Last Updated: 2024-11-21

When building Project S's API, I added a message field to a few endpoints, only to realize that was becoming confusing because some endpoints return a JSON representation of a single entity (e.g. Ticket or a User) and you cannot tell if message is a property of that entity or meta-information from the API.

By contrast, with enveloped API responses, you can of course add fields with meta-data, since there is no risk of clash.

{
  "data": {}, // ticket attributes
  "message": "whatever"
}

Lesson

Do not add extra meta fields (like "message") to an "un-enveloped" API response.