TT#13: "Tech talk on Contract-first Approach"

Contract-First Approach: Navigating Software Development with Clarity ??

Explanation:

The contract-first approach is a pivotal software development methodology where the design and definition of an application's interface—known as the contract—take precedence before the actual implementation. In this approach, the contract, often defined in a formal language like OpenAPI (formerly Swagger) or GraphQL SDL (Schema Definition Language), acts as the guiding blueprint for the entire system.

Analogy:

Picture constructing a building. Before a single brick is laid, architects meticulously craft detailed blueprints outlining the structure, design, and functionality. These blueprints form a contract between architects and builders, ensuring everyone is on the same page regarding expectations. Similarly, in software development, the contract-first approach involves creating a clear specification or interface (the blueprint) before diving into code (constructing the building).

Technical Details:

1. Interface Definition: Developers kick off the process by clearly defining the contract or interface of the application. This includes specifying data types, endpoints, methods, and their expected behavior. Tools like OpenAPI or GraphQL are commonly employed for this purpose.
2. Contract Validation: The defined contract undergoes validation and agreement by relevant stakeholders, including developers, testers, and clients. This step ensures a shared understanding of how the system should behave.
3. Code Generation: With the contract finalized, code can be automatically generated based on this blueprint. This ensures that the implemented code aligns precisely with the specified interface.
4. Interoperability: The contract-first approach is a champion for interoperability. Different parts of the system can be developed independently, as long as they adhere to the agreed-upon contract. This approach allows for parallel development of frontend and backend components without tight coupling.
5. Documentation: The contract serves as living documentation, making it easier for developers to comprehend how to interact with the system. It also facilitates API versioning and evolution, as changes to the contract are intentional and documented.

Benefits:

• Clarity and Alignment: Ensures a crystal-clear understanding of the system's behavior among all stakeholders.
• Interoperability: Promotes seamless collaboration between different components and systems.
• Consistency: Automatically generates consistent and accurate code based on the contract.
• Documentation: Acts as a comprehensive guide, serving as documentation for the entire system.

In essence, the contract-first approach provides a structured and collaborative path for software development, reducing ambiguity, and fostering improved communication among development teams. ????

Below is the contract snippet with detailed explanation. ??

openapi: 3.0.1
info:
  title: Products API
  version: '1.0'

servers:
  - url: https://localhost:8080

paths:
  /product:
    summary: This is a PRODUCT API
    description: This API does CRUD operation on PRODUCT data
    post:
      tags:
        - Product
      summary: Get all product by category
      operationId: 'getAllProductByCategory'
      requestBody:
        $ref: '#/components/requestBodies/ProductRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'

components:

  requestBodies:
    ProductRequest:
      description: Product request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProductRequest'

  schemas:
    ProductRequest:
      type: object
      required:
        - categoryName
      properties:
        categoryName:
          type: string

    ProductResponse:
      type: array
      items:
        $ref: '#/components/schemas/Product'

    Product:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        price:
          type: string
        quantity:
          type: string        

The provided OpenAPI contract (YAML file) describes an API for managing product data. Let's break down the key components of the contract:

1. OpenAPI Version and Info: openapi: 3.0.1: Specifies the version of the OpenAPI Specification being used.info: Contains metadata about the API. title: Products API: Describes the title of the API. version: '1.0': Specifies the version of the API.
2. Servers: servers: Specifies the base URL(s) for the API. url: https://localhost:8080: Indicates that the API is expected to be accessible at https://localhost:8080.
3. Paths: /product: Describes the endpoint for product-related operations. summary: A short summary of the purpose of the API endpoint. description: Additional details about the API endpoint. post: Defines the HTTP operation for creating a new product. tags: Categorizes the operation under the "Product" tag. summary: Briefly describes the purpose of the operation. operationId: A unique identifier for the operation. requestBody: Specifies the structure of the request payload. $ref: '#/components/requestBodies/ProductRequest': Refers to the definition of the request body schema in the components section. responses: Describes the possible HTTP responses. '200': Defines a successful response with HTTP status code 200. description: Describes the success response. content: Specifies the response content type. application/json: Indicates that the response content is in JSON format. schema: Refers to the definition of the response payload schema in the components section.
4. Components:requestBodies: Defines reusable request body components. ProductRequest: Describes the structure of the request body for product-related operations. description: Provides additional information about the request body. content: Specifies the supported content types and their schemas. application/json: Indicates that the request body should be in JSON format. schema: Refers to the definition of the request body schema in the components section. schemas: Defines reusable data models (schemas) for the API. ProductRequest: Describes the structure of the product request. type: object: Specifies that the schema represents an object. required: Lists the required properties. properties: Defines the properties of the object. categoryName: Describes a property representing the category name. type: string: Specifies that the property should be a string. ProductResponse: Describes the structure of the product response. type: array: Indicates that the response will contain an array of objects. items: Specifies the schema for individual items in the array. $ref: '#/components/schemas/Product': Refers to the definition of the product schema. Product: Describes the structure of a product. type: object: Specifies that the schema represents an object. properties: Defines the properties of the object. name, description, price, quantity: Properties representing product details, each specified as a string.

This OpenAPI contract provides a clear and standardized description of the Products API, including its endpoints, request and response structures, and data models. It serves as a comprehensive guide for API consumers and developers.

?? Unlocking Collaboration in Software Development: The Contract-First Approach

In the dynamic world of software development, envision an eCommerce venture with two crucial services: the Product Service and the Dashboard Service. Separate teams tackle these services, emphasizing efficiency and clear communication.

?? Team Collaboration:

• Product Service Team: This team crafts a contract YAML, a blueprint defining the API's structure, leveraging tools like OpenAPI. They publish this contract, laying the foundation for seamless collaboration.
• Dashboard Service Team: This team, responsible for the user interface, effortlessly integrates with the Product Service by adding a contract dependency. Thanks to the OpenAPI generator, server code materializes automatically.

?? Project Structure:

• Contract-Store Module (1st Module): Here resides the YAML contract, acting as the shared understanding between teams. In reality, it could exist in a standalone Git repository.
• Dashboard Module (2nd Module): This module links to the contract-store, generating server code effortlessly. This separation enables independent development and clearer dependencies.
• Product Module (3rd Module): Home to the actual API implementation, this module could be hosted in a distinct Git repository for modular development.

?? Demonstration:

Explore a practical example in this GitLab repository, showcasing the Contract-First Approach in action.

This methodology promotes structured collaboration, reducing ambiguity, and fostering better communication among development teams. Embrace clarity and efficiency in your software development journey!

?? Join the Conversation: Share this post with your friends and colleagues who are passionate about web development and tech innovation. Let's learn and grow together. Your network will thank you! ??