OpenAPI specifications are the industry standard for describing RESTful APIs. On our platform, these definitions act as a blueprint, powering the Developer API Reference and making it easy for you to understand, test, and integrate with our services.

Whether you are exploring available endpoints, checking required parameters, or reviewing data models, the OpenAPI definition provides everything you need in one place.

How OpenAPI powers your workflow

The OpenAPI specification is more than just documentation; it's a machine-readable contract that enables several developer tools.

flowchart LR
    A["OpenAPI Definition (JSON)"] --> B["Interactive API Docs"]
    A --> C["Code Generation"]
    A --> D["Automated Testing"]
    
    style A stroke:#3b82f6,stroke-width:2px

Anatomy of an OpenAPI definition

If you choose to look at the raw OpenAPI file (often named openapi.json), you'll notice it is divided into several key sections. Here is a breakdown of what each section means, using a sample "Plant Store" API as an example:

Reading an endpoint definition

When you explore an endpoint in the documentation, you are looking at a user-friendly version of the paths section. Here is how to break down an endpoint definition:

1. 1

   Identify the Path and Method

   Every action starts with an HTTP method (like GET, POST, or DELETE) and a path. For example, GET /plants retrieves a list of items, while DELETE /plants/{id} removes a specific item.

2. 2

   Check the Parameters

   Look for required and optional parameters. These might be in the URL path (like {id}), in the query string (like ?limit=10), or in the headers.

3. 3

   Review the Request Body

   For POST and PUT requests, you will usually need to send data. The documentation will show you the exact schema required. For instance, creating a new plant requires a JSON object with a name, an id, and an optional tag.

4. 4

   Understand the Responses

   APIs return status codes to indicate success or failure. A 200 OK usually means success and returns data, a 204 No Content means an item was successfully deleted, and a 400 indicates an unexpected error.

Core data models and schemas

To keep the API consistent, data structures are defined once as Schemas (found in the components section of the raw file) and reused across multiple endpoints.

For example, a Plant schema might look like this behind the scenes:

"Plant": {
  "required": ["name"],
  "type": "object",
  "properties": {
    "name": {
      "description": "The name of the plant",
      "type": "string"
    },
    "tag": {
      "description": "Tag to specify the type",
      "type": "string"
    }
  }
}

When you view the Core Data Models & Schemas section of our documentation, you'll see these objects neatly formatted into tables, detailing which fields are required and what data types they expect.

Webhooks

In addition to standard API endpoints, our OpenAPI definition supports webhooks. Webhooks describe out-of-band requests that your application can receive from our platform.

For example, the /plant/webhook definition outlines the payload you will receive when a new plant is added to the store, allowing you to build reactive integrations and process data in real-time.

Next steps

Now that you understand how our OpenAPI definitions are structured, you can start exploring the actual endpoints and integrating them into your application.