restful-api-guidelines.pdf

【实例简介】
【实例截图】
【核心代码】

Table of Contents
Zalando RESTful API and Event Scheme Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Conventions Used in These Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Zalando specific information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2. Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
API Design Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
API as a Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
API First . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3. General Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Must: Follow API First Principle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Must: Provide API Specification using OpenAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Must: only use Durable and Immutable Remote References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Should: Provide API User Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Must: Write APIs in U.S. English . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4. Meta Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Must: Contain API Meta Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Must: Use Semantic Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Must: Provide API Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Must: Provide API Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5. Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Must: Secure Endpoints with OAuth 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Must: Define and Assign Permissions (Scopes) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Must: Follow Naming Convention for Permissions (Scopes) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6. Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Must: Don’t Break Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Should: Prefer Compatible Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Must: Prepare Clients To Not Crash On Compatible API Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Should: Design APIs Conservatively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Must: Always Return JSON Objects As Top-Level Data Structures To Support Extensibility . . . . . 18
Must: Treat Open API Definitions As Open For Extension By Default . . . . . . . . . . . . . . . . . . . . . . . . . 19
Should: Used Open-Ended List of Values (x-extensible-enum) Instead of Enumerations . . . . . . . . 19
Should: Avoid Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Must: Use Media Type Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Must: Do Not Use URI Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7. Deprecation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Must: Obtain Approval of Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Must: External Partners Must Agree on Deprecation Timespan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Must: Reflect Deprecation in API Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1
Must: Monitor Usage of Deprecated APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Should: Add a Warning Header to Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Should: Add Monitoring for Warning Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Must: Not Start Using Deprecated APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
8. JSON Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Must: Property names must be ASCII snake_case (and never camelCase): ^[a-z_][a-z_0-9]*$ . . 23
Should: Define Maps Using additionalProperties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Should: Array names should be pluralized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Must: Boolean property values must not be null. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Should: Null values should have their fields removed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Should: Empty array values should not be null. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Should: Enumerations should be represented as Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Should: Date property values should conform to RFC 3339 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
May: Time durations and intervals could conform to ISO 8601. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
May: Standards could be used for Language, Country and Currency . . . . . . . . . . . . . . . . . . . . . . . . . 25
9. API Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Must/Should: Use Functional Naming Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Must: Follow Naming Convention for Hostnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Must: Use lowercase separate words with hyphens for Path Segments . . . . . . . . . . . . . . . . . . . . . . . 27
Must: Use snake_case (never camelCase) for Query Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Should: Prefer Hyphenated-Pascal-Case for HTTP header Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Must: Pluralize Resource Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Should: Not Use /api as Base Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Must: Avoid Trailing Slashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Must: Stick to Conventional Query Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
10. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Must: Avoid Actions — Think About Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Should: Model complete business processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Should: Define useful resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Must: Keep URLs Verb-Free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Must: Use Domain-Specific Resource Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Must: Use URL-friendly Resource Identifiers: [a-zA-Z0-9:._-]* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Must: Identify resources and Sub-Resources via Path Segments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Should: Only Use UUIDs If Necessary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
May: Consider Using (Non-) Nested URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Should: Limit number of Resource types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Should: Limit number of Sub-Resource Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
11. HTTP Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Must: Use HTTP Methods Correctly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Must: Fulfill Common Method Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Should: Consider To Design POST and PATCH Idempotent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2
Should: Use Secondary Key for Idempotent POST Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Should: Define Collection Format of Query Parameters and Headers . . . . . . . . . . . . . . . . . . . . . . . . . 39
Must: Document Implicit Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
12. HTTP Status Codes And Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Must: Specify Success and Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Must: Use Standard HTTP Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Must: Use Most Specific HTTP Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Must: Use Code 207 for Batch or Bulk Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Must: Use Code 429 with Headers for Rate Limits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Must: Use Problem JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Must: Do not expose Stack Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
13. Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Should: Reduce Bandwidth Needs and Improve Responsiveness. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Should: Use gzip Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Should: Support Partial Responses via Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Should: Allow Optional Embedding of Sub-Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Must: Document Cachable GET, HEAD, and POST Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
14. Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Must: Support Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Should: Prefer Cursor-Based Pagination, Avoid Offset-Based Pagination. . . . . . . . . . . . . . . . . . . . . . 52
May: Use Pagination Links Where Applicable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
15. Hypermedia. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Must: Use REST Maturity Level 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
May: Use REST Maturity Level 3 - HATEOAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Must: Use full, absolute URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Must: Use Common Hypertext Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Should: Use Simple Hypertext Controls for Pagination and Self-References . . . . . . . . . . . . . . . . . . . 56
Must: Not Use Link Headers with JSON entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
16. Data Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Must: Use JSON to Encode Structured Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
May: Use non JSON Media Types for Binary Data or Alternative Content Representations . . . . . . 56
Should: Prefer standard Media type name application/json. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Must: Use Standard Date and Time Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
May: Use Standards for Country, Language and Currency Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Must: Define Format for Type Number and Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
17. Common Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Should: Use a Common Money Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Must: Use common field names and semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
18. Common Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Must: Use Content-* Headers Correctly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
May: Use Standardized Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3
May: Use Content-Location Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Should: Use Location Header instead of Content-Location Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
May: Consider to Support Prefer Header to Handle Processing Preferences . . . . . . . . . . . . . . . . . . . 64
May: Consider to Support ETag Together With If-Match/If-None-Match Header . . . . . . . . . . . . . . . . . 64
May: Consider to Support Idempotency-Key Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
19. Proprietary Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Must: Use Only the Specified Proprietary Zalando Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Must: Propagate Proprietary Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Must: Use X-Flow-ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
20. API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Must: Publish OpenAPI Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Should: Monitor API Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
21. Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Must: Treat Events as part of the service interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Must: Make Event schema available for review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Must: Ensure Event schema conforms to Open API Schema Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Must: Ensure that Events are registered as Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Must: Ensure Events conform to a well-known Event Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Must: Ensure that Events define useful business resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Must: Events must not provide sensitive customer personal data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Must: Use the General Event Category to signal steps and arrival points in business processes . 82
Must: Use Data Change Events to signal mutations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Should: Provide a means for explicit event ordering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Should: Use the hash partition strategy for Data Change Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Should: Ensure that Data Change Events match API representations . . . . . . . . . . . . . . . . . . . . . . . . . 84
Must: Permissions on events must correspond to API permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Must: Indicate ownership of Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Must: Define Event Payloads in accordance with the overall Guidelines . . . . . . . . . . . . . . . . . . . . . . 85
Must: Maintain backwards compatibility for Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Should: Avoid additionalProperties in event type definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Must: Use unique Event identifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Should: Design for idempotent out-of-order processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Must: Follow Naming Convention for Event Type Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Must: Prepare for duplicate Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Appendix A: References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
OpenAPI Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Publications, specifications and standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Dissertations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Books. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Blogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Appendix B: Tooling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
4
Zalando RESTful API and Event Scheme
Guidelines
Zalando SE
Other formats: PDF, EPUB3
1. Introduction
Zalando’s software architecture centers around decoupled microservices that provide functionality
via RESTful APIs with a JSON payload. Small engineering teams own, deploy and operate these
microservices in their AWS (team) accounts. Our APIs most purely express what our systems do,
and are therefore highly valuable business assets. Designing high-quality, long-lasting APIs has
become even more critical for us since we started developing our new open platform strategy,
which transforms Zalando from an online shop into an expansive fashion platform. Our strategy
emphasizes developing lots of public APIs for our external business partners to use via third-party
applications.
With this in mind, we’ve adopted "API First" as one of our key engineering principles. Microservices
development begins with API definition outside the code and ideally involves ample peer-review
feedback to achieve high-quality APIs. API First encompasses a set of quality-related standards and
fosters a peer review culture including a lightweight review procedure. We encourage our teams to
follow them to ensure that our APIs:
• are easy to understand and learn
• are general and abstracted from specific implementation and use cases
• are robust and easy to use
• have a common look and feel
API First Integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Support Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Optimistic Locking in RESTful APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Appendix C: Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Rule Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95