Effective titles and descriptions for API components and operations provide guidance on summarizing functionality, detailing business rules, and including technical considerations such as authorization and idempotency.

Titles and descriptions for component schemas

Component schemas require clear and concise titles and descriptions to help developers understand their purpose and usage. Here are the recommeded guidelines:
  • For title, use a short, descriptive phrase that identifies the schema.
  • Begin the description with a concise sentence that summarizes the schema. Follow with detailed rules and constraints.

Summaries and descriptions for operations

Operations need summaries and descriptions that convey intent and technical details. Summaries should be brief, while descriptions can include multiple paragraphs. Recommended guidelines include:
  • Limit summary to 60 characters. State the purpose of the operation clearly.
  • For description, provide detailed information, including:
    • Business rule edge cases—Describe any exceptions or special conditions that apply to the operation.
    • Authorization expectations—Specify the required scopes or roles that are necessary to perform the operation.
    • Idempotency guarantees—Indicate whether the operation is idempotent and explain the conditions under which this guarantee holds.
    • Rate limit nuances—Provide information about any rate-limiting policies or thresholds that affect the operation.
    • Side effect notes—Explain any downstream workflows or triggers that occur as a result of executing the operation.