API outline overview
The API outline organizes the structure of an API into distinct sections. Each section represents a key aspect of API design, configuration, or behavior. The outline provides a clear view of the API’s components and helps you navigate and manage its definition efficiently.
- General information
- The General information section defines the core details of the API. It identifies, categorizes, and groups the API by using fields such as the title, description, version, contact details, license, and server URLs. You can also define variables that the API uses throughout the definition.
- Paths and Operations
-
The Paths and operations section defines the API’s resources and the HTTP methods associated with them. It explains how resources are structured, how methods are defined, and how requests and responses are modeled.
- Defining resources
- This part structures the API into resources that represent endpoints. It outlines the resource’s purpose, the supported HTTP methods, and any parameters required for requests.
- Defining methods
- This part explains how each method behaves. It sets the operation ID, assigns tags, and defines optional parameters and the request and response structure.
- Method requests
- This part describes the structure of the payload a method accepts. You define or reuse schemas for supported content types and include sample data for documentation and mocking.
- Method responses
- This part describes how the API returns responses. It specifies schemas, examples, headers, and links. When both a status code range and a specific code are defined, the specific code takes precedence.
- Security
- The Security section defines how the API manages authentication and authorization. It applies security schemes that protect the entire API or specific operations.
- Tags
- The Tags section groups operations with descriptive labels to support organization and filtering.
- Components
- The Components section contains reusable building blocks such as schemas, parameters, responses, examples, request bodies, headers, security schemes, and links. These reusable elements support consistent API design and reduce duplication.
- Documentation
- The Documentation section lets you link external documentation that provides additional guidance or context for API consumers.
- API mocking
- The API mocking section simulates API responses without relying on a live backend. This supports early testing, integration work, and iterative development.
- Scopes
- The Scopes section defines access control boundaries by grouping operations into permission sets that clients use to control access.
- Policy sequence
- The Policy sequence section lists the runtime policies applied to the API. These policies define rules for security, transformations, traffic control, and operational behavior.
- URI Schemes
- The URI Schemes section defines the communication protocols the API supports, such as HTTP or HTTPS.
- CORS
- The CORS section defines how the API handles cross-origin requests.Note: Parameters for the CORS policy are not provided within the policy. The policy retrieves its configuration from the
corssection of the API definition and enforces the rules defined in that section. - Properties
- The Properties section captures custom metadata associated with the API and stores additional configuration or business information.