Table of Contents

  1. Introduction
    1. Zalando specific information
  2. Table of Contents
  3. Design Principles
    1. API Design Principles
  4. General Guidelines
    1. Must: Provide API Reference Definition using OpenAPI
    2. Should: Provide User Manual Documentation
    3. Must: Write APIs in U.S. English
  5. Security
    1. Must: Secure Endpoints with OAuth 2.0
    2. Must: Define and Assign Access Rights (Scopes)
  6. Compatibility
    1. Must: Don’t Break Backward Compatibility
    2. Should: Prefer Compatible Extensions
    3. Must: Prepare Clients for Compatible API Extensions (the Robustness Principle)
    4. Must: Always Return JSON Objects As Top-Level Data Structures To Support Extensibility
    5. Should: Used Open-Ended List of Values (x-extensible-enum) Instead of Enumerations
    6. Should: Avoid Versioning
    7. Must: Use Media Type Versioning
    8. Must: Do Not Use URI Versioning
    9. Should: Provide Version Information in OpenAPI Documentation
  7. JSON Guidelines
    1. Must: Use Consistent Property Names
    2. Must: Use Consistent Property Values
  8. API Naming
    1. Must: Use lowercase separate words with hyphens for Path Segments
    2. Must: Use snake_case (never camelCase) for Query Parameters
    3. Must: Use Hyphenated HTTP Headers
    4. Should: Prefer Hyphenated-Pascal-Case for HTTP header Fields
    5. Could: Use Standardized Headers
    6. Must: Pluralize Resource Names
    7. Could: Use /api as first Path Segment
    8. Must: Avoid Trailing Slashes
    9. Could: Use Conventional Query Strings
  9. Resources
    1. Must: Avoid Actions — Think About Resources
    2. Should: Define useful resources
    3. Must: Keep URLs Verb-Free
    4. Must: Use Domain-Specific Resource Names
    5. Must: Identify resources and Sub-Resources via Path Segments
    6. Could: Consider Using (Non-) Nested URLs
    7. Should: Limit number of Resources
    8. Should: Limit number of Sub-Resource Levels
  10. HTTP
    1. Must: Use HTTP Methods Correctly
    2. Must: Fulfill Safeness and Idempotency Properties
    3. Must: Use Meaningful HTTP Status Codes
    4. Must: Provide Error Documentation
    5. Must: Use 429 with Headers for Rate Limits
  11. Performance
    1. Should: Reduce Bandwidth Needs and Improve Responsiveness
    2. Should: Use gzip Compression
    3. Should: Support Filtering of Resource Fields
    4. Could: Support the ETag Header
    5. Should: Allow Optional Embedding of Sub-Resources
  12. Pagination
    1. Must: Support Pagination
    2. Should: Prefer Cursor-Based Pagination, Avoid Offset-Based Pagination
    3. Could: Use Pagination Links Where Applicable
  13. Hypermedia
    1. Must: Use REST Maturity Level 2
    2. Could: Use REST Maturity Level 3 - HATEOAS
    3. Must: Use a well-defined subset of HAL
    4. Must: Do Not Use Link Headers with JSON entities
    5. Could: Use Custom Link Relations
  14. Data Formats
    1. Must: Use JSON as the Body Payload
    2. Could: Use other Media Types than JSON
    3. Must: Use Standard Date and Time Formats
    4. Could: Use Standards for Country, Language and Currency Codes
    5. Could: Use Application-Specific Content Types
  15. Common Data Objects
    1. Should: Use a Common Money Object
    2. Should: Use Common Address Fields
    3. Must: Use Problem JSON
    4. Must: Do not expose Stack Traces
  16. Common Headers
    1. Must: Use Content Headers Correctly
    2. Must: Use Content-Location Correctly
    3. Could: Use the Prefer header to indicate processing preferences
  17. Proprietary Headers
  18. Deprecation
    1. Must: Obtain Approval of Clients
    2. Must: External Partners Must Agree on Deprecation Timespan
    3. Must: Reflect Deprecation in API Definition
    4. Must: Monitor Usage of Deprecated APIs
    5. Should: Add a Warning Header to Responses
    6. Should: Add Monitoring for Warning Header
    7. Must: Not Start Using Deprecated APIs
  19. API Operation
    1. Must: Applications Must Provide Online Access to Their API (Swagger) Definitions
    2. Should: Monitor API Usage
  20. Events
    1. Must: Treat Events as part of the service interface
    2. Must: Ensure that Events define useful business resources
    3. Must: Ensure that Event Types conform to Nakadi's API
    4. Must: Events must not provide sensitive customer personal data.
    5. Must: Use Business Events to signal steps and arrival points in business processes
    6. Must: Use Data Change Events to signal mutations
    7. Should: Use the hash partition strategy for Data Change Events
    8. Should: Ensure that Data Change Events match API representations
    9. Must: Indicate ownership of Event Types
    10. Must: Define Event Payloads in accordance with the overall Guidelines
    11. Must: Maintain backwards compatibility for Events
    12. Must: Use unique Event identifiers
    13. Must: Follow conventions for Event Type names
  21. References
    1. OpenAPI Specification
    2. Publications, specifications and standards
    3. Dissertations
    4. Books
    5. Blogs
  22. Tooling
    1. API First Integrations
    2. Support Libraries