6. API Documentation

What is Contract-First Design?

Contract-First Design is a software development approach that revolves around contracts—formal definitions of interfaces and messages exchanged between systems. In this approach, the API or service structure is precisely defined before any code is written. These contracts usually include:

• Inputs and outputs
• Data types and their structure
• Validation rules
• Possible errors and error messages

Simply put, in Contract-First Design, the contract between systems is designed first, and the actual code is implemented afterwards. This is the opposite of Code-First Design, where code is written first and the API is generated based on it.

Benefits of Contract-First Design

1. Clarity and transparency: Everything is defined in the contract before development begins.
2. Reduced inconsistencies: Different systems or teams can work independently based on a fixed contract.
3. Early testing: Contracts allow for creating mock APIs, enabling testing and simulation before implementing the real logic.
4. Automatic documentation: Contracts can be used to generate API documentation, eliminating the need for separate documentation.
5. Parallel team development: Teams can work simultaneously without needing access to each other’s code.

Why We Use Contract-First Design in the Horizon Project?

In the Horizon project, we work with a distributed and modular system, where different components must interact accurately and reliably. The main reasons we adopt Contract-First Design in Horizon are:

1. Team coordination: Each team can work on its own service without waiting for other parts to be completed.
2. API stability: Once the contract is defined, unexpected changes are minimized, reducing future issues.
3. Facilitates testing and simulation: Contracts allow creating mock services and testing complex scenarios before actual implementation.
4. Consistent and accurate documentation: API documentation always reflects the contract and stays up-to-date as services evolve.
5. Reduced inter-service errors: In a multi-module system like Horizon, Contract-First ensures transparent and error-free interactions between modules.

Tool

One of the tools for testing and documenting APIs of the Horizon project is Hoppscotch, which is a free and open source alternative to Postman. The API test file will be executable with this tool.

API Documentation

Some of API documents are listed as below.

1. API Specification
   1. Basic Data
   2. User Management
   3. Document Management
   4. Human Resource
2. System Error List
3. Horizon API Test File