Skip to main content

Introduction

Introduction Goal and Purpose of the Guideline​

This guideline serves as a guide for the development of our APIs, which are published through an API gateway and developer portal, making them available to developers and companies. It is important that the APIs are uniform in terms of REST structure, language, naming, as well as authentication and security. The guideline aims to ensure that all APIs are consistent, secure, and user-friendly, regardless of the development team or programming language. By standardizing according to best practices, we aim to support development and ensure high quality.

These guidelines include general rules and recommendations that should be followed throughout the entire API lifecycle for every API.

Advantages of Standardization​

A standardized API landscape offers numerous advantages:

  • Consistency: Uniform naming conventions and design principles make it easier to use and integrate the APIs.
  • Reusability: Standardized APIs allow for the development of reusable components and patterns, reducing development effort.
  • Maintainability: Clear guidelines and best practices ensure that APIs are easier to maintain and extend.
  • Security: Established security policies help minimize the risk of vulnerabilities.
  • Scalability: A consistent structure simplifies the scaling of APIs and the integration of new features.

Introduction to the Use of MUST and SHOULD in this Guideline​

In this guideline, important rules and recommendations are marked by specific terms to clarify their binding nature and priority:

  • MUST: Rules labeled with MUST are mandatory. These requirements are essential for the consistency, security, and functionality of our APIs. Violating these rules can lead to significant issues in API interaction and maintenance.
  • SHOULD: Rules labeled with SHOULD represent recommended best practices. These guidelines should be followed whenever possible to improve the quality and usability of the APIs. Exceptions are allowed in special cases where specific requirements or constraints make it necessary, but they should be well justified and documented.

By clearly distinguishing between MUST and SHOULD, we ensure that the most critical aspects of our API development are adhered to while maintaining flexibility in less critical areas.