API Developer

Core Workflow

• Analyze Requirements: Understand the business needs and define the API endpoints required.

• Design API: Create API designs that follow RESTful principles and best practices.

• Implement Endpoints: Develop the API endpoints with appropriate HTTP methods and status codes.

• Secure API: Implement authentication and authorization mechanisms.

• Document API: Use OpenAPI/Swagger to document the API endpoints, request/response formats, and error codes.

• Test API: Perform thorough testing to ensure functionality, security, and performance.

• Monitor API: Set up monitoring to track API usage, performance, and errors.

• Maintain API: Regularly update the API to fix bugs, improve performance, and add new features.

• Version API: Implement versioning strategies to manage breaking changes.

Reference Guide

Load the detailed guidance based on on context:

Topic Reference Load When

HTTP Methods references/01-http-methods.md When deciding on appropriate HTTP methods for endpoints

Resource Naming references/02-resource-naming.md When naming API endpoints and structuring URL hierarchies

Versioning references/03-versioning.md When planning breaking changes or deprecating API versions

Status Codes references/04-status-codes.md When choosing HTTP status codes for responses

Filtering & Pagination references/05-filtering-pagination.md When implementing list endpoints with filtering, sorting, or pagination

Response Shape references/06-response-shape.md When structuring JSON response envelopes for data and errors

Including Related Data references/07-including-related-data.md When implementing optional expansion of related resources

Field Naming references/08-field-naming.md When defining field names in request/response payloads

Datetime Handling references/09-datetime-handling.md When working with dates and times in API payloads

Authentication & Tokens references/10-authentication-tokens.md When implementing authentication or token management

Rate Limiting references/11-rate-limiting.md When implementing request throttling or abuse prevention

Security Basics references/12-security-basics.md When reviewing API security or handling untrusted input

Validation Errors references/13-validation-errors.md When formatting validation error responses

Caching references/14-caching.md When implementing HTTP caching for GET endpoints

Idempotency references/15-idempotency.md When ensuring safe retries for mutating operations

Error Handling references/16-error-handling.md When mapping exceptions to API error responses

Documentation references/17-documentation.md When creating or updating OpenAPI specs

Deprecation references/18-deprecation.md When planning to retire or replace API endpoints

Consistency Rules references/19-consistency-rules.md When reviewing API design for style guide compliance

Pre-Release Checklist references/20-pre-release-checklist.md Before releasing a new API or major endpoint

Constraints

MUST DO

• Must follow RESTful principles and best practices.

• Ensure all endpoints are secure and protected against common vulnerabilities.

• Document all API endpoints clearly using OpenAPI/Swagger.

• Implement proper error handling and return meaningful status codes.

• Monitor API performance and set up alerts for downtime or errors.

MUST NOT DO

• Expose sensitive data through the API.

• Implement breaking changes without proper versioning.

• Ignore performance optimization opportunities.

• Overcomplicate API designs; keep them simple and intuitive.

• Neglect testing; ensure all endpoints are thoroughly tested before deployment.