Sitemap

About

Provide feedback

API Design Guidelines

• API Guidelines Summary
• Spectral Rules
  • SHOULD
    • SHOULD always return json objects as top level data structures
    • SHOULD declare enum values using upper snake case format
    • SHOULD define api root
    • should have location header in 201 response
    • SHOULD limit number of resource types
    • SHOULD limit number of sub resource levels
    • SHOULD prefer standard media type names
    • SHOULD support application/json content request body
    • SHOULD use hyphenated pascal case for header parameters
    • SHOULD use standard http status codes
    • SHOULD use x-extensible-enum
  • MUST
    • MUST define a format for integer types
    • MUST define 400, 404, and 500 responses
    • MUST define security schemes
    • MUST have info description
    • MUST have info title
    • MUST have info value chain
    • MUST return 200 for api root
    • MUST specify default response
    • MUST use camel case for property names
    • MUST use camel case for query parameters
    • MUST use normalised paths
    • MUST use valid problem json schema
    • MUST define a format for number types
    • MUST define 401 and 403 for secured operations
    • MUST have info api audience
    • MUST have info contact email
    • MUST have info contact name
    • MUST have info contact url
    • MUST have info version
    • MUST NOT define request body for GET requests
    • MUST NOT use http basic authentication
    • MUST NOT use uri versioning
    • MUST use https protocol only
    • MUST use lowercase with hyphens for path segments
    • use normalised paths without empty path segments
    • MUST use problem json as default response
    • MUST use problem json for errors
    • MUST use valid version info schema
• API Guidelines
  • API Design
  • API Specification & Documentation
  • Common Data Types
  • Data Standards
  • Error Handling
  • Governance
  • Integration Patterns
  • Naming Conventions
  • Organisational Data Models
  • Pagination, Filtering & Sorting
  • Security
  • Testing
  • Versioning and Deprecation
  • Performance, Reliability & Monitoring
    • Caching
    • Monitoring & Observability
    • Resilience Patterns

Development Standards

• Cloud security alignment
• DORA metrics
• Environments
• GDS service standard alignment
• Measuring security maturity
• Non-Functional Requirements (NFRs)
• Penetration testing
• Secure coding and tooling
• Security champions
• Security
• Threat modelling
• Exceptions
• Source control
• Static analysis
• Appendix
  • Approved cryptographic standards
  • Non-functional requirements
  • Branch protection rules
  • Threat modelling deliverables