Defining API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• api-reference/openapi.json
• docs.json
• README.md
• api-reference/endpoint/get.mdx
• api-reference/endpoint/create.mdx
• api-reference/endpoint/delete.mdx

This document outlines how API endpoints are defined, structured, and documented within the project. The primary mechanism for API definition is an OpenAPI 3.1.0 specification file. This specification serves as the single source of truth for the API's capabilities, data models, and security requirements.

The API documentation pages are generated based on this OpenAPI file and organized through a central configuration file, docs.json. This configuration maps the API endpoints to the navigation structure of the documentation website, providing a clear and organized reference for developers. The sample API described is for a "Plant Store," which serves as a demonstration of OpenAPI features.

Sources: api-reference/openapi.json:2-8, docs.json:13-48

Core API Specification

The API is formally defined in api-reference/openapi.json using the OpenAPI 3.1.0 standard. This file contains all information about the API, including metadata, server details, security schemes, paths, and data schemas.

Sources: api-reference/openapi.json:2

API Metadata and Server

The info object provides high-level information about the API. All API requests are directed to a single sandbox server.

Key	Value
title	OpenAPI Plant Store
description	A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification.
version	1.0.0
license	MIT
server url	http://sandbox.mintlify.com

Sources: api-reference/openapi.json:3-14

Security

The API uses a Bearer Token for authentication. All protected endpoints require an Authorization header with a bearer token. This is defined under securitySchemes and applied globally.

"security": [
  {
    "bearerAuth": []
  }
],
...
"components": {
  ...
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer"
    }
  }
}

Sources: api-reference/openapi.json:16-20, api-reference/openapi.json:208-214

Endpoint Definitions

API endpoints are defined under the paths object in the OpenAPI specification. The Plant Store API exposes endpoints for managing plants.

Sources: api-reference/openapi.json:21-140

GET /plants

This endpoint retrieves a list of all plants. It supports an optional query parameter to limit the number of results.

The following diagram illustrates the request and response flow for this endpoint.

Parameters

Name	In	Description	Type	Format
limit	query	The maximum number of results to return	integer	int32

Sources: api-reference/openapi.json:26-34

Responses

• 200 OK: Returns a JSON array of Plant objects.
• 400 Bad Request: Returns an Error object if an unexpected error occurs.

Sources: api-reference/openapi.json:35-56

POST /plants

This endpoint creates a new plant in the store. The request body must contain a NewPlant object.

Request Body
The body of the request must be a JSON object conforming to the NewPlant schema.

"requestBody": {
  "description": "Plant to add to the store",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/NewPlant"
      }
    }
  },
  "required": true
}

Sources: api-reference/openapi.json:61-71

Responses

• 200 OK: Returns the newly created Plant object.
• 400 Bad Request: Returns an Error object on failure.

Sources: api-reference/openapi.json:72-91

DELETE /plants/{id}

This endpoint deletes a single plant identified by its id.

Parameters

Name	In	Description	Type	Format	Required
id	path	ID of plant to delete	integer	int64	true

Sources: api-reference/openapi.json:97-106

Responses

• 204 No Content: Indicates the plant was successfully deleted. The response has no body.
• 400 Bad Request: Returns an Error object on failure.

Sources: api-reference/openapi.json:107-120

Webhooks

The API defines a webhook to notify external systems when a new plant is added.

Sources: api-reference/openapi.json:124-140

POST /plant/webhook

This webhook is triggered when a new plant is added to the store. The receiving server should be configured to accept a POST request at its endpoint. The request body contains the NewPlant object.

The following diagram shows the webhook flow.

Responses

• 200 OK: The webhook consumer should return a 200 status to acknowledge successful receipt of the data.

Sources: api-reference/openapi.json:136-138

Data Models

Data models are defined as reusable schemas in the components/schemas section of openapi.json.

Sources: api-reference/openapi.json:141-207

The diagram below shows the relationship between the Plant and NewPlant schemas. NewPlant inherits all properties from Plant and adds an id.

Plant Schema

The base object for a plant.

Property	Type	Description	Required
name	string	The name of the plant	Yes
tag	string	Tag to specify the type	No

Sources: api-reference/openapi.json:144-159

NewPlant Schema

Represents a new plant being added to the store. It includes all properties from Plant plus an id.

Property	Type	Description	Required
id	integer	Identification number of the plant	Yes
name	string	The name of the plant	Yes
tag	string	Tag to specify the type	No

Sources: api-reference/openapi.json:160-187

Error Schema

A standard error object returned for 4xx responses.

Property	Type	Description	Required
error	integer	Error code	Yes
message	string	Error message	Yes

Sources: api-reference/openapi.json:188-206

Documentation Navigation

The API reference pages are organized in the main documentation configuration file, docs.json. This file defines the navigation tabs and groups that structure the documentation site.

The "API reference" tab is configured to group related endpoint examples.

{
  "tab": "API reference",
  "groups": [
    {
      "group": "API documentation",
      "pages": [
        "api-reference/introduction"
      ]
    },
    {
      "group": "Endpoint examples",
      "pages": [
        "api-reference/endpoint/get",
        "api-reference/endpoint/create",
        "api-reference/endpoint/delete",
        "api-reference/endpoint/webhook"
      ]
    }
  ]
}

This structure ensures that the documentation for each endpoint (e.g., get.mdx, create.mdx) is logically organized and easy for users to find.

Sources: docs.json:28-48, api-reference/endpoint/get.mdx, api-reference/endpoint/create.mdx, api-reference/endpoint/delete.mdx