In OpenAPI 3.0, how do I create a link from a list of entities to a single entity?

Question

In most OpenAPI 3.0 documentation (like the official one), links are introduced with a combination of a POST endpoint to create an entity returning an ID linking to a GET endpoint to fetch that entity by that same returned ID:

1. POST /users -> UserID
2. GET /users/{UserID} -> User

In Schemathesis context, this would assume an empty data storage and simulate a create+fetch scenario. I would like to test my GET endpoints on a pre-warmed data storage and implement a "fetch a list, then fetch each entity from the list by ID" scenario:

1. GET /users -> List[User] -> List[UserID]
2. GET /users/{UserID} -> User for each entry in the list

For this to work, I need an OpenAPI link from the list GET endpoint to the entity GET endpoint, however I can't seem to find either an example or a confirmation that this is indeed possible.

Can I and if so how can I create such a link in OpenAPI 3.0?

Answer 1

OpenAPI links are defined using JSON Pointers. JSON Pointers are quite limited - they can only point to a specific field within a JSON Structure (such as "the first element of this array", or the entire array) and don't support wildcard expressions (such as "any/each element of this array").

This means, for example, that if you have the GET /users endpoint that returns

[
  {
    "id": "29d590d1-02b2-4aa1-9ce5-98202cc9a619",
    "username": "nikolai",
    ...
  },
  {
    "id": "58091b14-eb06-47ee-b896-50cebdda20ef",
    "username": "helen",
    ...
  },
  ...
]

you can define a link like $response.body#/0/id to indicate that the id of the first user in the list can be used as a parameter to another endpoint. But there's no way for a link to reference an arbitrary/each user from the list.

You can check these discussions in the OpenAPI Specification repository for more details:

• Link for array element
• Variables/Parameters in Links