Tech Due Diligence ARCH-3: API Design and Integration Strategy
What This Control Requires
The assessor evaluates the quality of API design, including RESTful principles, versioning strategy, documentation, rate limiting, authentication, and the overall approach to internal and external integrations.
In Plain Language
Well-designed APIs signal a team that thinks carefully about interfaces, extensibility, and long-term maintainability. For acquirers and investors, the API layer is a strong indicator of how easily the product can support integrations, partner ecosystems, and new clients without constant rework.
Assessors look at the consistency of your REST or GraphQL design, how you handle versioning and backward compatibility, authentication and authorisation, rate limiting, error handling conventions, and documentation quality (ideally auto-generated from code). For microservices architectures, they also evaluate service discovery, circuit breaking, and retry patterns between services.
Poor API design creates friction everywhere - for customers trying to integrate, partners building on your platform, and your own developers adding features. Getting this right early pays off enormously as the product scales.
How to Implement
Follow established conventions for your API style. For REST APIs, that means using appropriate HTTP methods (GET, POST, PUT, PATCH, DELETE), returning meaningful status codes, keeping URL structures and resource naming consistent, supporting pagination, filtering, and sorting on collection endpoints, and implementing discoverability for public APIs.
Introduce API versioning from the start. Pick a strategy (URL path versioning /v1/, header versioning, or query parameter) and stick with it. Define a deprecation policy giving consumers adequate notice - at least 6 months - before retiring old versions.
Generate documentation from code using OpenAPI/Swagger, GraphQL introspection, or similar tooling. Cover endpoint descriptions and use cases, request and response schemas with examples, authentication requirements, rate limiting details, error codes, and change history.
Set up rate limiting to protect against abuse and ensure fair usage. Define limits per client, per endpoint, or per tier. Return standard headers (X-RateLimit-Remaining, Retry-After) so clients can handle throttling gracefully.
Secure every API with proper authentication and authorisation. Use OAuth 2.0 or API keys for external APIs, JWT or session tokens for internal ones, and scope-based or role-based authorisation for granular access control. Never leave endpoints unauthenticated unless they are genuinely public.
Build resilience into service-to-service communication with circuit breakers to prevent cascade failures, retry with exponential backoff for transient errors, timeouts to prevent resource exhaustion, and bulkhead patterns to isolate failure domains.
Monitor API performance and usage continuously. Track response time percentiles, error rates by endpoint, usage patterns by client, and deprecation timeline compliance. These metrics help catch performance regressions, identify popular endpoints, and track migration progress for deprecated versions.
Evidence Your Auditor Will Request
- API documentation (auto-generated from code preferred)
- API versioning strategy documentation
- Rate limiting configuration and monitoring
- API authentication and authorisation implementation
- API performance monitoring dashboard
Common Mistakes
- Inconsistent API design: different conventions used across endpoints
- No API versioning; breaking changes applied without consumer notification
- API documentation is manual and out of sync with implementation
- No rate limiting; APIs vulnerable to abuse and resource exhaustion
- Authentication bypass possible on certain endpoints
Related Controls Across Frameworks
Frequently Asked Questions
REST or GraphQL: which is preferred?
Do internal APIs need the same level of design rigour as external APIs?
Track Tech Due Diligence compliance in one place
AuditFront helps you manage every Tech Due Diligence control, collect evidence, and stay audit-ready.
Start Free Assessment