Core Principles
API First
Everyone must (MUST) follow the API-First principle. The API-First principle is an extension of the Design-First approach. Therefore, the development of an API must (MUST) always begin with API design, without any preliminary coding work. The API design (e.g., description, schema) is the authoritative source of truth, not the API implementation. The API implementation must (MUST) always align with the respective API design, which represents the contract between the API and its users.
Contract Between Stakeholders and Consumers
A published API design serves as a contract between all who use or work on it. Before making changes to the API, these changes must be documented and approved in the design.
This approach ensures that the API remains stable, consistent, and usable in the long term, while helping to detect unexpected changes early on.
Common Data Types
Important data types for APIs and JSON data
| Data Type | Standard | Example |
|---|---|---|
| Date and Time | ISO 8601 | 2017-06-21T14:07:17Z (Always use UTC) |
| Date | ISO 8601 | 2017-06-21 |
| Duration | ISO 8601 | P3Y6M4DT12H30M5S |
| Time interval | ISO 8601 | 2007-03-01T13:00:00Z/2008-05-11T15:30:00Z |
| Timestamps | ISO 8601 | 2017-01-01T12:00:00Z |
| Language Codes | ISO 639 | en ↔ English |
| Country Code | ISO 3166-1 alpha-2 | DE ↔ Germany |
| Currency | ISO 4217 | EUR ↔ Euro |
| UUID | RFC 4122 | 123e4567-e89b-12d3-a456-426614174000 |
| Email Addresses | RFC 5322 | example@example.com |
| URLs | RFC 3986 | https://www.example.com |
| Phone Numbers | E.164 | +4915212345678 |
| IP Addresses | IPv4, IPv6 | 192.0.2.1 (IPv4), 2001:0db8:85a3:0000:0000:8a2e:0370:7334 (IPv6) |
| Color Values | HEX, RGB, RGBA | #FFFFFF, rgb(255, 255, 255), rgba(255, 255, 255, 1.0) |
Rules for Extensions
- Backward Compatibility: All extensions must (MUST) be backward compatible. This means that existing clients should continue to function without adjustments. Changes must not break existing interfaces or data structures.
- Adding New Fields: New fields should (SHOULD) be added rather than modifying or removing existing ones. New fields MUST be designed to be optional and accept empty or null values by default to avoid impacting existing clients.
- Versioning: If an extension represents a significant change that is not backward compatible, a new version of the API must (MUST) be created. Versioning must (MUST) be clearly indicated in the URL.
- Extending Existing Endpoints: Where possible, existing endpoints should (SHOULD) be extended to support new functionality rather than creating new endpoints. This helps keep the API organized and maintainable.
- **Documentation: **All extensions must (MUST) be clearly described in the API documentation. This includes detailed information about new fields, endpoints, and any changes to existing structures.
- Backward Compatibility Testing: Comprehensive tests must (MUST) be conducted before releasing extensions to ensure that existing functionality is not affected.
- Consistency: New extensions must (MUST) follow the existing naming conventions and design principles of the API to ensure a consistent and predictable API structure.