API Reference Overview

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/introduction.mdx (Referenced in docs.json)
• api-reference/endpoint/get.mdx (Referenced in docs.json)

This document provides a comprehensive overview of the OpenAPI Plant Store API, a sample API used to demonstrate features of the OpenAPI specification. The API allows for managing a collection of plants, including creating, retrieving, and deleting them. The documentation for this API is structured within the "API reference" tab of the Mint Starter Kit, as defined in the project's navigation configuration.

The API is served from a single sandbox environment and uses bearer token authentication for securing its endpoints. It defines several data models for representing plants and errors, and includes both standard REST endpoints and a webhook for asynchronous notifications.

Sources: api-reference/openapi.json:3-9, docs.json:36-38

API Architecture

The API is defined using the OpenAPI 3.1.0 specification. It exposes a set of RESTful endpoints and a webhook for managing a plant store. All API requests are directed to a single server URL.

• Server URL: http://sandbox.mintlify.com

Sources: api-reference/openapi.json:2, api-reference/openapi.json:11-16

Authentication

The API uses Bearer Token authentication. All requests to secured endpoints must include an Authorization header with a valid bearer token.

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

Sources: api-reference/openapi.json:18-22, api-reference/openapi.json:206-212

API Interaction Flow

The following diagram illustrates the general flow of interaction between a client and the Plant Store API.

This diagram shows a client making a request, the server processing it, and returning a response.
Sources: api-reference/openapi.json:11-22

Endpoints

The API provides endpoints for managing plants and a webhook for notifications. The documentation for these endpoints is organized under the "API documentation" and "Endpoint examples" groups.

Sources: docs.json:39-50

Endpoint Summary

Method	Path	Description
GET	/plants	Returns all plants from the system.
POST	/plants	Creates a new plant in the store.
DELETE	/plants/{id}	Deletes a single plant based on the ID supplied.
POST	/plant/webhook	Webhook for new plant notifications.

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

GET /plants

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

Parameters

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

Responses

• 200 OK: Returns an array of Plant objects.
• 400 Bad Request: An unexpected error occurred. Returns an Error object.

Sources: api-reference/openapi.json:27-59

POST /plants

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

Request Body

• application/json: A NewPlant object.

Responses

• 200 OK: Returns the created Plant object.
• 400 Bad Request: An unexpected error occurred. Returns an Error object.

Sources: api-reference/openapi.json:60-92

DELETE /plants/{id}

Deletes a specific plant identified by its id.

Parameters

Name	In	Type	Required	Description
id	path	integer	True	ID of plant to delete.

Responses

• 204 No Content: The plant was successfully deleted.
• 400 Bad Request: An unexpected error occurred. Returns an Error object.

Sources: api-reference/openapi.json:94-123

Webhook: POST /plant/webhook

This webhook endpoint is designed to receive notifications about a new plant being added to the store. The system posting to this webhook should send a NewPlant object in the request body.

Request Body

• application/json: A NewPlant object.

Responses

• 200 OK: Acknowledges successful receipt of the data.

The following diagram shows the webhook notification flow.

Data Models (Schemas)

The API uses several schemas to define the structure of data for requests and responses. These are defined in the components/schemas section of the OpenAPI specification.

Sources: api-reference/openapi.json:171-205

The relationship between the data models is shown below.

This diagram shows that NewPlant includes all properties of Plant plus an id.
Sources: api-reference/openapi.json:173-200

Plant Schema

Represents a plant in the store.

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

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

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

NewPlant Schema

Represents a new plant being added to the store. It includes all fields from the Plant schema, plus a required id.

Field	Type	Required	Description
id	integer	Yes	Identification number of the plant.
...	-	-	All fields from Plant.

Sources: api-reference/openapi.json:189-200

Error Schema

Represents an error response.

Field	Type	Required	Description
error	integer	Yes	Error code.
message	string	Yes	Error message.

Sources: api-reference/openapi.json:201-205

Development and Publishing

To work on this documentation locally, the Mintlify CLI can be used. The mint dev command starts a local preview server. Changes are published automatically by pushing to the default branch of the GitHub repository.

Sources: README.md:13-26

Summary

The OpenAPI Plant Store API provides a clear and simple interface for managing plant data. It is defined by an openapi.json file, which specifies all endpoints, authentication methods, and data schemas. The documentation itself is built using Mintlify, with the structure and navigation controlled by docs.json, making it a well-documented example project.

Sources: api-reference/openapi.json, docs.json, README.md