Skip to main content

API & Integration Overview

APIs (Application Programming Interfaces) are the contracts that allow software components to communicate. This section provides comprehensive guidelines for designing, implementing, and integrating HTTP-based APIs using REST, GraphQL, and OpenAPI contracts.

API Documentation Structure​

Our API guidelines are organized by topic to help you find relevant information quickly:

REST API Design​

REST Fundamentals - Core REST principles, HTTP methods, status codes, and resource modeling. Start here for REST basics.

REST Patterns - Pagination, filtering, sorting, searching, idempotency keys, and async operations. Essential patterns for scalable REST APIs.

REST Versioning - API versioning strategies, backward compatibility, deprecation processes, and migration paths.

GraphQL​

GraphQL - GraphQL schema design, queries, mutations, when to use GraphQL vs REST, and implementation patterns.

API Contracts​

API Contracts - Contract-first development, request/response modeling, validation, and contract testing.

OpenAPI Specifications - Writing OpenAPI specs, contract-first design, and generating documentation.

OpenAPI Backend Integration - Implementing APIs in Spring Boot using OpenAPI contracts.

OpenAPI Frontend Integration - Generating TypeScript clients from OpenAPI specs for React and Angular.

General API Patterns​

API Patterns - Error handling, circuit breakers, retries, resilience patterns, and async processing patterns that apply across REST and GraphQL.

API Design Principles​

Good API design follows these core principles:

1. Design for Consumers - Start with consumer needs, not your data model. Ask what tasks consumers are trying to accomplish and what would make the API easiest to use.

2. Be Consistent - Establish conventions (naming, error formats, pagination) and follow them everywhere. Consistency reduces cognitive load.

3. Use Standard Patterns - Leverage REST, GraphQL, OpenAPI, and gRPC rather than inventing custom protocols. Standards improve discoverability and reduce learning curve.

4. Design for Evolution - Plan for change through versioning, additive changes, deprecation periods, and backward compatibility.

5. Security by Default - Build in authentication, authorization, input validation, rate limiting, and HTTPS from the start.

See REST Fundamentals for REST-specific principles or GraphQL for GraphQL design patterns.

When to Use Each API Style​

Use REST for:

  • Standard CRUD operations on resources
  • Public-facing APIs (widely understood)
  • APIs where caching is important
  • Resource-oriented data models

Characteristics: Resource-oriented URIs, HTTP verbs, stateless, standard status codes, JSON/XML responses.

→ Start here: REST Fundamentals

GraphQL​

Use GraphQL for:

  • Clients needing flexible data fetching
  • Fetching multiple related resources in a single request
  • Strong typing requirements
  • Client teams controlling data needs

Characteristics: Query language, schema-driven, type-safe, single endpoint, client-specified responses.

→ Learn more: GraphQL

Trade-offs: More complex to implement than REST, caching is harder, requires different tooling.

API Development Workflow​

1. Design the Contract First​

Define the API contract before implementing:

Contract-first enables parallel development, stakeholder review before implementation, and auto-generated documentation.

2. Review the Contract​

Get feedback from:

  • Consumers: Do they find it intuitive?
  • Security: Are there vulnerabilities?
  • Architecture: Does it align with system design?
  • Standards: Does it follow team conventions?

3. Implement Provider and Consumer​

Backend: Implement API following the contract. See OpenAPI Backend Integration.

Frontend: Generate typed clients from contracts. See OpenAPI Frontend Integration.

4. Test the Contract​

Verify provider and consumer match the contract:

5. Document and Deploy​

  • Auto-generate documentation from OpenAPI specs (Swagger UI, ReDoc)
  • Include getting started guide, authentication guide, examples
  • Monitor API metrics and errors in production

Quick Reference​

Essential Patterns​

Pagination - Always paginate collections. Use cursor-based pagination for large datasets.

Filtering & Sorting - Support query parameters for filtering and sorting. See REST Patterns.

Error Handling - Use consistent error responses with HTTP status codes, error codes, and messages. See API Patterns.

Versioning - Use URL versioning (/api/v1/, /api/v2/) for major versions.

Idempotency - Make POST operations safe to retry using idempotency keys.

Async Operations - Return 202 Accepted with job tracking URL for long-running operations.

Security Checklist​

  • HTTPS only (redirect HTTP to HTTPS)
  • Authentication (OAuth 2.0, JWT, API keys)
  • Authorization (verify permissions per operation)
  • Input validation (never trust client input)
  • Rate limiting (prevent abuse)
  • Never expose internal errors to clients

→ See: Security Overview

Observability Checklist​

  • Structured logging with correlation IDs
  • Metrics (request rate, error rate, latency)
  • Distributed tracing across services
  • Monitoring and alerting

→ See: Observability Overview

Common Anti-Patterns to Avoid​

Chatty APIs - Requiring many requests to accomplish a task. Solution: Provide composite endpoints or use GraphQL.

Leaky Abstractions - Exposing internal implementation details in URIs (e.g., /database/users/select). Solution: Design resource-oriented APIs.

Ignoring HTTP Semantics - Misusing HTTP methods (POST for reads) or status codes (200 with error body). Solution: Use HTTP correctly - see REST Fundamentals.

No Pagination - Returning unbounded collections. Solution: Always paginate - see REST Patterns.

No Versioning Strategy - Breaking clients without warning. Solution: Plan for versioning - see REST Versioning.

Framework Implementation​

Cross-Cutting Concerns​

Testing​

Further Learning​

Study Well-Designed APIs:

Specifications and Standards:

Books:

  • RESTful Web Services by Leonard Richardson & Sam Ruby
  • Designing Web APIs by Brenda Jin et al.
  • API Design Patterns by JJ Geewax