liveBook · Manning

Design-first approach

As explained in Spring Start Here, Second Edition

A contract-first approach develops an API by specifying its interface before implementing the endpoint and generating implementation artifacts from that specification.

A design-first, or contract-first, approach defines a REST API in a specification before implementing its endpoints. The contract describes details such as HTTP methods, paths, request bodies, and responses; tools can generate part of the endpoint implementation from it. section 10.3.3

Starting with a shared contract can help teams:

  • Keep APIs consistent by generating implementations from the same structure and standards. section 10.3.3
  • Share endpoint expectations across backend and frontend teams without relying on Java code. section 10.3.3
  • Generate API documentation from the contract. section 10.3.3
openapi: 3.0.3
info:
  title: Payment API
  description: API for processing payments
  version: 1.0.0
paths:
  /payment:    #A
    post:   #B
      summary: Make a payment
      operationId: makePayment    #C
      requestBody:    #D
        description: Payment details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentDetails'
      responses:     #E
        '200':
          description: Payment processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentDetails'
components:
  schemas:
    PaymentDetails:    #F
      type: object
      properties:
        amount:
          type: number
          format: double
          example: 100.50

The Payment API contract describes a POST /payment endpoint, its request body, response, and PaymentDetails schema. section 10.3.3

How Spring Start Here, Second Edition covers it

How deep it goes
Defines contract fields and shows endpoint generation, but defers detailed instruction on using OpenAPI.
Examples
Uses a Payment API contract for POST /payment, with a PaymentDetails request body and response schema.
What you can do after
Build it from scratch by defining an OpenAPI contract and generating part of a Spring endpoint implementation.
How it connects
Connects REST APIs with OpenAPI specifications and generated endpoint implementations.

Also explained in

Compare how 3 books explain design-first approach →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Spring Start Here, Second Edition. The section links point to the parts of the book it draws on.