Introduction

Contract (OAS) driven development

API management in the platform follows a contract-driven development approach to ensure consistency, maintainability, and ease of integration. The API contract serves as a formal description of the service's interface.

Contracts can be created using either a code-first or contract-first approach, depending on the team's preference and use case.

Regardless of the approach chosen always service's contracts is defined and stored within service's repository.

contract/contract.yaml

This is valid for any commit (branch...). There is a pipeline step responsible for checking this consistency.

The service contract is independent of any other service. However, it may share the same DTOs defined in C# code. Nonetheless, at the contract level, it remains independent—DTOs can be defined multiple times, even with different names or prefixes.

Code first (preferred)

The code-first approach is the platform's preferred method for API contract development. In this approach:

• OpenAPI Specification (OAS) contracts are automatically generated during the build process.
• The presentation layer (API controllers) is responsible for:
  • Defining and maintaining the contract.
  • Managing versioning to ensure backward compatibility.
• API controllers are pre-configured in the service template, making it easy for developers to start building APIs. Additional patterns, like minimal APIs, may be supported in the future.

Contract first

In the contract-first approach:

• API development begins with the creation of an OAS contract.
• Code (e.g., C# classes, controllers) is generated from the OAS contract using tools like the OAS Code Generator (currently planned for migration).
• This approach is useful when API design needs to be finalized before development begins.

Endpoints exposure

By default, no API endpoint is exposed to ensure security and clarity. Endpoints must be explicitly declared and configured.

Configuration Requirements

• Endpoints are defined in a configuration file (contract/config.json).
• Configuration includes:
  • API contract details.
  • Security requirements (e.g., authentication methods).

Gateways

Endpoints are exposed via gateways, each catering to specific responsibilities:

• Self-Care Gateway: For customer-facing applications (mobile and web).
• PBA Gateway: For administrative applications.

Contracts for self-care and PBA must be designed to remain independent to avoid cross-dependencies.

Client packages

To simplify API consumption for clients, client packages can be automatically generated in various languages, such as:

• TypeScript
• Dart

The generation process is managed through a dedicated repository: API Contracts Code Generator.

Gateway configuration

The gateway contract is formed by merging the individual service contracts. This consolidated configuration is used to define the behavior and routing of the gateway.

Key features

• Gateway configuration is generated based on:
  • Service contracts.
  • Configuration files specific to the gateway technology in use (e.g., Kubernetes Gateway API, Istio, NGINX Ingress, Tyk, KrakenD).
• Detailed guidance on gateways is available here: Gateways Documentation.

Benefits

• Consistency: Ensures uniform API design across services.
• Security: Only explicitly declared endpoints are exposed.
• Scalability: Independent contracts for self-care and PBA enable modular and scalable architectures.
• Developer Efficiency: Tools and templates streamline API development and integration.