Fundamentals and Core Concepts

Design-First Approach

Creating intentional API contracts:

Design-First Process:

• Identify API consumers and use cases
• Define API requirements and scope
• Create API specification (OpenAPI, AsyncAPI)
• Review design with stakeholders
• Validate with mock implementations
• Refine based on feedback
• Finalize API contract

API Specification Standards:

• OpenAPI (REST APIs)
• AsyncAPI (Event-driven APIs)
• GraphQL Schema
• gRPC Protocol Buffers
• RAML
• API Blueprint

Example OpenAPI Specification:

openapi: 3.0.3
info:
  title: Customer API
  description: API for managing customer information
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /customers:
    get:
      summary: List customers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
    post:
      summary: Create customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreate'
      responses:
        '201':
          description: Customer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        status:
          type: string
          enum: [active, inactive, pending]
      required:
        - id
        - firstName
        - lastName
        - email
        - status

Design Tools and Platforms:

• Swagger Editor/UI
• Stoplight Studio
• Postman
• Insomnia
• APIMatic
• Redocly

API Design Standards

Establishing consistent design principles:

Design Principles:

• Resource-oriented design
• Consistency and predictability
• Backward compatibility
• Forward compatibility
• Simplicity and clarity
• Security by design
• Performance considerations

REST API Standards:

• Resource naming conventions
• HTTP method usage
• Status code usage
• Query parameter patterns
• Pagination approach
• Filtering and sorting
• Versioning strategy
• Error handling

Example REST API Guidelines:

1. Resource Naming:
   - Use plural nouns for collections: /customers, /orders
   - Use concrete names over abstract concepts
   - Use lowercase, kebab-case for multi-word resources
   - Avoid verbs in resource paths (except for actions)

2. HTTP Methods:
   - GET: Retrieve resources (safe, idempotent)
   - POST: Create resources or actions
   - PUT: Replace resources (idempotent)
   - PATCH: Partial updates (idempotent)
   - DELETE: Remove resources (idempotent)

3. Status Codes:
   - 200 OK: Successful GET, PUT, PATCH
   - 201 Created: Successful POST that creates a resource
   - 204 No Content: Successful DELETE or action with no response
   - 400 Bad Request: Invalid request format
   - 401 Unauthorized: Authentication required
   - 403 Forbidden: Authenticated but not authorized
   - 404 Not Found: Resource doesn't exist
   - 422 Unprocessable Entity: Validation errors

GraphQL Standards:

• Schema design principles
• Type naming conventions
• Query structure
• Mutation patterns
• Error handling
• Pagination approach
• Authentication and authorization
• Performance considerations

Event-Driven API Standards:

• Event naming conventions
• Event payload structure
• Event versioning
• Event schema evolution
• Delivery guarantees
• Error handling
• Event metadata

API Implementation and Delivery

Contract-First Development

Building APIs based on established contracts:

Contract-First Workflow:

• Start with approved API specification
• Generate server stubs and client SDKs
• Implement business logic
• Validate against API contract
• Automate testing against specification
• Deploy with continuous validation

Code Generation Tools:

• OpenAPI Generator
• Swagger Codegen
• NSwag
• GraphQL Code Generator
• Protocol Buffers Compiler
• AsyncAPI Generator

Example OpenAPI Code Generation:

# Generate server stubs for Spring Boot
openapi-generator generate \
  -i customer-api.yaml \
  -g spring \
  -o server/ \
  --additional-properties=library=spring-boot

# Generate client SDK for TypeScript
openapi-generator generate \
  -i customer-api.yaml \
  -g typescript-fetch \
  -o client/ \
  --additional-properties=supportsES6=true

Contract Validation:

• API linting
• Schema validation
• Contract testing
• Consumer-driven contract testing
• Automated compliance checks
• Runtime contract enforcement