[ADP-49] API Term Registration
reviewing phase 1
- This article should provide an internal registration page but not yet.
- This article does not define the process of registration update yet.
Overview
This article tries to establish a unified API term registration process to ensure consistency and standardization of API-related terminology across the organization. The process is inspired by the IANA registration procedures, adapting them to our organizational context.
Notice: The following is a draft and may not be final. It is subject to change and should be treated as a work in progress. We may add more registration types in the future.
Standard Details
Problem Type Registration
- Definition: A process for registering new problem types used in API error responses.
- Registration process MUST include: a. Proposal submission b. Review by API Governance Team c. Approval and addition to the official problem type registry
- Documentation MUST include:
- Problem type identifier
- Description
- Required attributes
- Optional attributes
- Example usage
HTTP Custom Preference Registration
- Definition: A process for registering custom HTTP preferences used in API requests.
- Registration process MUST include: a. Proposal submission with justification b. Review for potential conflicts with existing standards c. Approval and documentation
- Documentation MUST include:
- Preference name
- Description
- Syntax
- Intended use cases
Application ID Registration (URN or Custom MIME Type)
- Definition: A process for registering unique application identifiers, either as URNs or custom MIME types.
- Registration process MUST include: a. Submission of application ID proposal b. Review for uniqueness and adherence to naming conventions c. Approval and addition to the organization's application ID registry
- Documentation MUST include:
- Application ID (URN or MIME type)
- Description of the application
- Version information (if applicable)
- Usage guidelines
Custom Header Registration
- Definition: A process for registering custom HTTP headers used in API requests and responses.
- Registration process MUST include: a. Proposal submission with justification b. Review for potential conflicts with existing standards c. Approval and documentation
- Documentation MUST include:
- Header name
- Description
- Syntax
- Applicable to (Request, Response, or Both)
- Usage guidelines
Link Relation Registration
- Definition: A process for registering link relation types used in API responses.
- Registration process MUST include: a. Proposal submission with justification b. Review for potential conflicts with existing standards c. Approval and documentation
- Documentation MUST include:
- Relation name
- Description
- Reference
- Usage guidelines
Authorization Schema Registration
- Definition: A process for registering authorization schemas used in API security.
- Registration process MUST include: a. Proposal submission with justification and security considerations b. Review by API Governance Team and Security Team c. Approval and documentation
- Documentation MUST include:
- Schema name
- Description
- Token format (if applicable)
- Header format
- Required claims or parameters
- Optional claims or parameters
- Usage guidelines
Term Maintenance and Accessibility
- The organization MUST maintain a central repository for all registered terms, problem types, preferences, and application IDs.
- The organization MUST implement a regular review process to ensure all registered items remain relevant and up-to-date.
- The organization MUST provide search and browsing capabilities for easy access to registered items.
Compliance
- All API designs and implementations MUST use registered terms, problem types, preferences, and application IDs where applicable.
Responsibilities
- API Governance Team SHALL oversee the registration processes, review submissions, and maintain the registries.
- API Designers and Developers SHALL submit new items for registration and MUST use registered items in their work.
- Documentation Team SHALL ensure consistent use of registered items in API documentation.
Related Standards
Example Registrations
Problem Type Registry
| Problem Type | Description | Required Attributes | Optional Attributes | Example Usage |
|---|---|---|---|---|
| https://api.example.com/problems/resource-not-found | Indicates that the requested resource does not exist | detail, instance | title | {"type": "https://api.example.com/problems/resource-not-found", "title": "Resource Not Found", "detail": "The requested user with ID 12345 does not exist", "instance": "/users/12345"} |
| https://api.example.com/problems/invalid-input | Indicates that the provided input is invalid | detail, errors | title, instance | {"type": "https://api.example.com/problems/invalid-input", "title": "Invalid Input", "detail": "The provided data failed validation", "errors": [{"field": "email", "message": "Invalid email format"}]} |
HTTP Custom Preference Registry
| Preference Name | Description | Syntax | Intended Use Cases |
|---|---|---|---|
| example-api-version | Specifies the desired API version | example-api-version=YYYY-MM-DD | Allow clients to request specific API versions |
| example-response-format | Specifies the desired response format | example-response-format=(json|xml) | Allow clients to request specific response formats |
Application ID Registry
| Application ID | Description | Version | Usage Guidelines |
|---|---|---|---|
| urn:example:app:inventory-management | Inventory Management Application | 1.0 | Use this URN to identify the Inventory Management Application in API requests and responses |
| application/vnd.example.user-profile+json | Custom MIME type for user profile data | N/A | Use this MIME type when sending or receiving user profile data in JSON format |
Custom Header Registry
| Header Name | Description | Syntax | Applicable to | Usage Guidelines |
|---|---|---|---|---|
| X-API-Key | Used for API authentication | X-API-Key: <api_key> | Request | Include this header in all API requests for authentication purposes |
| X-Rate-Limit-Remaining | Indicates the number of requests remaining in the current rate limit window | X-Rate-Limit-Remaining: <integer> | Response | Check this header in API responses to manage request rates and avoid exceeding limits |
| X-Request-ID | Unique identifier for the request, used for tracing and debugging | X-Request-ID: <uuid> | Both | Generate a unique ID for each request and include it in both the request and response headers for tracing purposes |
Link Relation Registry
| Relation Name | Description | Reference | Usage Guidelines |
|---|---|---|---|
| next | Indicates that the link's context is a part of a series, and that the next in the series is the link target | [RFC5988] | Use in pagination to link to the next page of results |
| self | Conveys an identifier for the link's context | [RFC5988] | Use to provide a canonical URL for a resource |
Authorization Schema Registry
| Schema Name | Description | Token Format | Header Format | Required Claims/Parameters | Optional Claims/Parameters | Usage Guidelines | Security Considerations |
|---|---|---|---|---|---|---|---|
| Bearer Token | A simple token-based authentication scheme | JWT | Authorization: Bearer <token> | iss, sub, exp | aud, nbf, iat | Use for most API authentication scenarios | Ensure tokens are transmitted over HTTPS; Validate all claims |