Table of Contents

  1. Introduction
    1. Conventions Used in These Guidelines
    2. Zalando specific information
  2. Table of Contents
  3. Principles
    1. API as a Product
    2. API Design Principles
  4. General Guidelines
    1. Must: Follow API First Principle
    2. Must: Provide API Reference Definition using OpenAPI
    3. Should: Provide User Manual Documentation
    4. 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 To Not Crash On Compatible API Extensions
    4. Should: Design APIs Conservatively
    5. Must: Always Return JSON Objects As Top-Level Data Structures To Support Extensibility
    6. Must: Treat Open API Definitions As Open For Extension By Default
    7. Should: Used Open-Ended List of Values (x-extensible-enum) Instead of Enumerations
    8. Should: Avoid Versioning
    9. Must: Use Media Type Versioning
    10. Must: Do Not Use URI Versioning
    11. 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. May: Use Standardized Headers
    6. Must: Pluralize Resource Names
    7. May: Use /api as first Path Segment
    8. Must: Avoid Trailing Slashes
    9. May: Use Conventional Query Strings
  9. Resources
    1. Must: Avoid Actions — Think About Resources
    2. Should: Model complete business processes
    3. Should: Define useful resources
    4. Must: Keep URLs Verb-Free
    5. Must: Use Domain-Specific Resource Names
    6. Must: Identify resources and Sub-Resources via Path Segments
    7. Should: Only Use UUIDs If Necessary
    8. May: Consider Using (Non-) Nested URLs
    9. Should: Limit number of Resources
    10. 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 Specific HTTP Status Codes
    4. Must: Provide Error Documentation
    5. Must: Use 207 for Batch or Bulk Requests
    6. Must: Use 429 with Headers for Rate Limits
    7. Should: Explicitly define the Collection Format of Query Parameters
  11. Performance
    1. Should: Reduce Bandwidth Needs and Improve Responsiveness
    2. Should: Use gzip Compression
    3. Should: Support Filtering of Resource Fields
    4. Should: Allow Optional Embedding of Sub-Resources
  12. Pagination
    1. Must: Support Pagination
    2. Should: Prefer Cursor-Based Pagination, Avoid Offset-Based Pagination
    3. May: Use Pagination Links Where Applicable
  13. Hypermedia
    1. Must: Use REST Maturity Level 2
    2. May: Use REST Maturity Level 3 - HATEOAS
    3. Must: Use Common Hypertext Controls
    4. Should: Use Simple Hypertext Controls for Pagination and Self-References
    5. Must: Not Use Link Headers with JSON entities
  14. Data Formats
    1. Must: Use JSON to Encode Structured Data
    2. May: Use non JSON Media Types for Binary Data or Alternative Content Representations
    3. Must: Use Standard Date and Time Formats
    4. May: Use Standards for Country, Language and Currency Codes
    5. Must: Define Format for Type Number and Integer
    6. Should: Prefer standard Media type name application/json
  15. Common Data Types
    1. Should: Use a Common Money Object
    2. Must: Use common field names and semantics
    3. Must: Follow Hypertext Control Conventions
    4. Must: Use Problem JSON
    5. Must: Do not expose Stack Traces
  16. Common Headers
    1. Must: Use Content Headers Correctly
    2. May: Use Content-Location Header
    3. Should: Use Location Header instead of Content-Location Header
    4. May: Use the Prefer header to indicate processing preferences
    5. May: Consider using ETag together with If-(None-)Match header
  17. Proprietary Headers
    1. Must: Use Only the Specified Proprietary Zalando Headers
    2. Must: Propagate 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: Provide Online Access to OpenAPI Reference Definition
    2. Should: Monitor API Usage
  20. Events
    1. Must: Treat Events as part of the service interface
    2. Must: Make Events available for review
    3. Must: Ensure Event Type schemas conform to Open API's Schema Object
    4. Must: Ensure that Events define useful business resources
    5. Must: Ensure that events conform to Zalando's event types
    6. Must: Events must not provide sensitive customer personal data.
    7. Must: Use Business Events to signal steps and arrival points in business processes
    8. Must: Use Data Change Events to signal mutations
    9. Should: Provide a means for explicit event ordering
    10. Should: Use the hash partition strategy for Data Change Events
    11. Should: Ensure that Data Change Events match API representations
    12. Must: Permissions on events must correspond to API permissions
    13. Must: Indicate ownership of Event Types
    14. Must: Define Event Payloads in accordance with the overall Guidelines
    15. Must: Maintain backwards compatibility for Events
    16. Should: Avoid additionalProperties in event type definitions
    17. Must: Use unique Event identifiers
    18. Should: Design for idempotent out-of-order processing
    19. Must: Follow conventions for Event Type names
    20. Must: Prepare for duplicate Events
  21. Appendix: References
    1. OpenAPI Specification
    2. Publications, specifications and standards
    3. Dissertations
    4. Books
    5. Blogs
  22. Appendix: Tooling
    1. API First Integrations
    2. Support Libraries
  23. Appendix: Changelog
    1. Rule Changes