Skip to main content

In-a-nutshell

The following points represent mandatory requirements (MUST) in our REST API guideline and must be adhered to during the development of our APIs. In addition to these essential requirements, the guidelines include further recommendations and best practices aimed at promoting consistency and quality in API development. By distinguishing between mandatory and recommended measures, these guidelines provide a foundation for the creation of our APIs while maintaining flexibility in less critical areas.

Summary​

  • API First Principle: Create the API design before programming.
  • Data Types: Use uniform standards (e.g., ISO 8601 for date/time).
  • Extensions: Ensure backward compatibility; version significant changes.
  • REST-Design: Stateless, use Cache-Control and ETag headers, enable layered system.
  • API Design: Resource-oriented URLs, consistent naming conventions (camelCase for query parameters and body, kebab-case for paths), versioning in URL.
  • HTTP-Methods: Use GET, POST, PUT, PATCH, DELETE correctly; use standardized status codes.
  • Error Handling: Return errors in JSON format (error, message, details).
  • Parameters: Clear path and query parameters (camelCase), support pagination and sorting.
  • Header-Parameters: Use standardized headers (Content-Type, Accept, Authorization), document them.
  • Security: Implement authentication (OAuth 2.0, JWT), HTTPS (TLS/SSL), enable CORS, and rate limiting.
  • Documentation: Document APIs with OpenAPI Specification (version 3.0.x), including complete error codes.

The points mentioned here are further specified and explained in the following sections: