API Design tip: use objects for similar data

Let's say you're building an API, be it RESTful or GraphQL, and you want to provide a few bits of similar data. Or maybe you've only got one piece of data (i.e an external identifier, but you rightfully so are thinking about future-proofing your API.

For instance, if we're building a Pipeline service, that executes CI/CD pipelines, we may initially reach for the following setup:

{
  "pipeline_id": "123",
  "namespace_id": "...",
  "namespace_path": "...",
  "project_id": "...",
  "project_path": "...",
  "user_id": "...",
  "user_login": "...",
  "user_email": "..."
}

Instead, it's better to wrap this into a specific object, such as:

{
  "pipeline_id": "123",
  "namespace": {
    "id": "...",
    "path": "..."
  },
  "project": {
    "id": "...",
    "path": "..."
  },
  "user": {
    "id": "...",
    "login": "...",
    "email": "..."
  }
}

This gives us an easier structure, which is easier to visually parse, and keeps similar data together. Instead of doing this later - as a breaking change - we can design it up front, and it works nicely.

It also can highlight where data is not owned by the service, as it's not top-level.