Skip to Content
OpenAPI HubResponsesLinks

OpenAPI Links

The Links object is a map of Link Objects or References to Link Objects that allows for describing possible API-use scenarios between different operations. For example, if a response returns a Drink object, and the Drink object has an ingredients property that is a list of Ingredient objects, then a link can be defined to the listIngredients operation showing how the ingredients can be used as an input to the listIngredients operation.

For example:

/drink/{name}:
  get:
    operationId: getDrink
      summary: Get a drink.
      description: Get a drink by name, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      tags:
        - drinks
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
    responses:
      "200":
        description: A drink.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Drink"
        links:
          listIngredients:
            operationId: listIngredients
            parameters:
              ingredients: $response.body#/ingredients
            description: The list of ingredients returned by the `getDrink` operation can be used as an input to the `listIngredients` operation, to retrieve additional details about the ingredients required to make the drink.
/ingredients:
    get:
      operationId: listIngredients
      summary: Get a list of ingredients.
      description: Get a list of ingredients, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      tags:
        - ingredients
      parameters:
        - name: ingredients
          in: query
          description: A list of ingredients to filter by. If not provided all ingredients will be returned.
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: A list of ingredients.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Ingredient"
        "5XX":
          $ref: "#/components/responses/APIError"
        default:
          $ref: "#/components/responses/UnknownError"

The Link Object represents a possible link that can be followed from the response.

Link Object Fields

Field
Type
String
Description
The
of an operation that exists in the document. Use either this field or the
field, not both.
Required
✅
Type
String
Description
Either a Relative Reference or Absolute Reference to an operation that exists in the document. Use either this field or the
field, not both.
Required
✅
Type
String
Description
A description of the link and intentions for its use. This may contain CommonMark syntax  to provide a rich description.
Required
Type
Map[string, any | {Expression}]
Description
A map of parameters to pass to the linked operation. The key is the name of the parameter and the value is either a constant value or an Expression that will be evaluated. The parameter name can also be qualified with the location of the parameter, for example,
or
Required
Type
Any | {Expression}
Description
A constant value or Expression that will be used as the request body when calling the linked operation.
Required
Description
An optional server to be used by the linked operation.
Required
Description
Any number of extension fields can be added to the link object that can be used by tooling and vendors.
Required

An example of OperationRef:

links:
  listIngredients:
    operationRef: "#/paths/~1ingredients/get"
    parameters:
      ingredients: $response.body#/ingredients
 
# or
 
links:
  listIngredients:
    operationRef: "https://speakeasy.bar/#/paths/~1ingredients/get"
    parameters:
      ingredients: $response.body#/ingredients

Last updated on