Link Objects in OpenAPI — Defining API Relationships

In this tutorial, you will learn about Link Objects in OpenAPI. We cover key concepts, practical examples, and best practices to help you master this topic.

Link objects in OpenAPI define relationships between operations, describing how the response of one operation can be used to call another operation, enabling dynamic API navigation.

What You'll Learn

You will learn how to define link objects, use runtime expressions to extract values from responses, and document API relationships for discoverability.

flowchart LR
  A[GET /users/{id}] --> B[Response]
  B --> C[Link: getUserDocuments]
  C --> D[GET /users/{id}/documents]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Link Definition

paths:
  /users/{userId}:
    get:
      operationId: getUser
      responses:
        "200":
          description: User details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
          links:
            getUserDocuments:
              operationId: listUserDocuments
              parameters:
                userId: "$response.body#/id"
              description: Gets documents for this user

  /users/{userId}/documents:
    get:
      operationId: listUserDocuments
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer

Common Mistakes

1. Incorrect runtime expressions — Wrong path to response body values.
2. No link descriptions — Links without explanations.
3. Hardcoded parameters — Not using runtime expressions.

Practice Questions

1. What is the purpose of link objects?
2. How do runtime expressions extract values from responses?
3. How do links enable API discoverability?
4. What happens if the linked operation does not exist?

Challenge

Define links for an order management API: GET order links to GET order items, GET customer, GET payment, and GET shipment. Use runtime expressions to pass IDs.

What's Next

In the next lesson, you will learn about OpenAPI tools and editors.