Skip to content

template.md

Latest commit

 

History

History
118 lines (74 loc) · 3.69 KB

template.md

File metadata and controls

118 lines (74 loc) · 3.69 KB

[Feature Name] API

[Lead Paragraph: Briefly describe the API. What is it? What specific problem does it solve for the developer? Use the "Jobs to be Done" framework: "This API allows [User Role] to [Action] so that they can [Benefit]."]

Strategic Overview

[Question: Why would a customer use this specific feature? What is the business value? Is it for compliance, user experience, automation, or data extraction?]

Key Use Cases

  • [Primary Use Case]: [Describe the most common scenario.]
  • [Secondary Use Case]: [Describe an edge case or secondary benefit.]
  • [Integration Scenario]: [How does this fit into a larger ecosystem?]

Real-Time vs. Latency Expectations

[Question: Is this API real-time? If there is a delay (e.g., data propagation, indexing), specify it here.]

  • Data Availability: [e.g., "Available 5 minutes after event" or "Real-time synchronous response"]
  • Retention Policy: [How long is this data stored?]

Required Permissions & Scopes

[Clearly list what the developer needs to enable before their first request.]

1. Configure OAuth Scopes

To successfully authenticate, your application must be configured with the following permissions in the Developer Portal:

  • [Scope Name]: [Explanation of why this scope is needed.]

2. Enable Platform Permissions

[Question: Does the user need a specific toggle enabled in the Admin UI? List the path here.]

  1. Log in to [Portal Name].
  2. Navigate to [Menu] > [Sub-menu].
  3. [Specific Action, e.g., "Check the 'Enable API' box"].

!!! warning "Common Authorization Errors" [Insert the most common error JSON the user will see if permissions/scopes are missing.]

API Discovery

[If there is a 'Discovery' or 'Schema' endpoint used to find valid values for the main API, document it here.]

[METHOD] [URL]

Prerequisites & Constraints

  • [Constraint 1]: [e.g., "Account ID is always required in the header"]
  • [Constraint 2]: [e.g., "Date formats must follow ISO-8601 with an explicit offset"]

Main Endpoint: [Endpoint Name]

[METHOD] [URL]

Request Body / Parameters

Parameter Type Requirement Description
[param_name] [Type] Required [What does this field do?]
[param_name] [Type] Optional [Default behavior if omitted?]

Example Request:

[JSON_REQUEST_EXAMPLE_GOES_HERE]

Response Details

[Break down the response object, focusing on fields that aren't self-explanatory.]

Field Type Description
[field_name] [Type] [Brief description of the data returned.]

[Nested Object Name] Structure

[If the response contains a complex nested object or array, break it down in a sub-section here.]

Implementation Strategy

[Provide a high-level strategy for how this API should be integrated into a production system.]

Recommended Pattern

[Question: Is there a specific polling frequency or webhook strategy recommended for this data?]

!!! important "Rate Limiting & Stability"

  • Limit: [X] requests per [Time Unit].
  • Strategy: [e.g., "Implement exponential backoff on 429 errors."]

Sample Implementation ([Language])

[Provide a clean, well-commented code snippet showing a real-world use of the API.]

# [Language] Example: [Action Being Performed]
[CODE_EXAMPLE_GOES_HERE]

Appendix: Supported Elements

[Use this section for long lists of constants, error codes, or supported entity types.]

??? info "View Supported [Elements/Entities]"

| Element | Description |
| :--- | :--- |
| `[Value A]` | [Explanation] |
| `[Value B]` | [Explanation] |