- Clearly distinguish between POST, PATCH, and PUT to ensure proper usage and behavior in API interactions.
- Adhere to RESTful naming conventions for external endpoints. Utilize nouns (e.g.,
accounts
) rather than verbs (e.g.,createAccount
) for endpoint names.- Since HTTP methods (GET, POST, PUT, etc.) imply action, additional verbs in the endpoint URL are redundant.
- Use plural nouns (e.g.,
accounts
) for endpoints to intuitively indicate collections or groups of resources. - Implement nested endpoints to denote relationships, like
api.foo.com/v1/accounts/{account_id}/users
. - Avoid leading numerals in field names for broader language compatibility.
- Employ standard HTTP status codes for feedback (2xx for success, 4xx for client errors, 5xx for server errors).
- Ensure error messages are informative, guiding users on how to rectify issues.
- Include a
debugging_id
in responses to assist in troubleshooting. - Maintain a consistent response schema, defaulting unpopulated fields to
null
.
- Use OpenAPI for API specification documentation, ensuring continuous validation against actual API requests.
- Prioritize the provision of sandbox environments for integration, mirroring production API behavior as closely as possible.
- Make error responses meaningful and constructive, offering debugging tips or workarounds where possible.
- Use UPPER_SNAKE_CASE for enums and lower_snake_case for field names.
- Adopt UTC for timezones, except for future dates.
- Include
created
andupdated
timestamps in all responses. - Prefer UUIDv7 for resource identifiers, presenting them in Base62 encoding to users, prefixed with a resource identifier (e.g.
vid_HLlvJYKurU6taLvIyYiYWX6OndSzSymw
). Great article on why: https://buildkite.com/blog/goodbye-integers-hello-uuids.
- Ensure HTTP bodies are valid JSON and headers specify
application/json
. - Implement idempotency in POST requests using an
Idempotency-Key
header. - Show all fields in responses, even if data is absent (marked as
null
). - Standardize date formatting to RFC 3339.
- Implement cursor-based pagination in API responses, ensuring chronological order and a standard pagination wrapper.
- Utilize pre-signed URLs for file uploads, ensuring file validation.
- Expose and request only essential data to minimize API surface and simplify changes.
- Aim for sub-250ms p99 latency.
- Log and monitor metrics (request counts, response times) at various system layers, redacting sensitive information.
- Use distributed tracing to identify system bottlenecks.
- Opt for OLAP/Snowflake solutions only for predictable query loads.
- Design database models to accommodate anticipated query patterns and scalability.
- Regularly load test systems to identify performance issues.
- Use job IDs for long-running queries.
- Set field data limits and consider rate limiting to protect system integrity.
- Avoid logging personal identifiable information (PII).
- Restrict public access to admin API endpoints, isolating them in separate services.
- Sanitize inputs to prevent XSS attacks.
- Establish a bug bounty program for additional security oversight.
- Control pagination using
limit
,start_after
, andending_before
parameters. - Default to 50 and cap page sizes at 100.
- Calculate
has_more
by querying for one extra item beyond the page size.
- Assuming rows A, B, C, D, E (ascending order):
limit=2
returnsE, D
.starting_after=D&limit=2
returnsC, B
.ending_before=D&limit=2
returnsE
.ending_before=A&limit=2
returnsC, B
.