Building and Deploying a New API (Part 1)

This blog post details the initial steps in building a new API, focusing on setting up the project structure and generating the initial code. The goal is to create a robust and testable API using a variety of modern tools.

The technology stack includes: OpenAPI for specification, oapi-codegen for server generation, Testify for testing, Codecov for coverage reporting, Docker for containerization, PostgreSQL for the database, GORM as the ORM, Flyway for database migrations, Kubernetes for orchestration, Terraform for infrastructure as code, and Caddy as the potential web server.

API Specification:

The project begins with a simple OpenAPI specification for a User resource. The User schema includes an id, email, and name. The id is read-only, and the email is write-only.

<code>components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: 123
          readOnly: true
        email:
          type: string
          example: me@example.com
          writeOnly: true
        name: 
          type: string
          example: Alice</code>

This schema will be used to define a POST endpoint at /users, returning a 201 (Created) status code on success and a Problem Details JSON Object for 400 (Bad Request) errors.

Code Generation:

oapi-codegen is used to generate the server code from the OpenAPI specification. Configuration files (server.config.yaml and types.config.yaml) are used to customize the generated code. A tools.go file utilizes go generate to automate this process.

Handler Implementation and Testing:

A basic server struct is created, implementing the generated server interface. A PostUser handler is implemented, initially returning nil values. Unit tests using Testify are written concurrently to define the expected behavior. Since the database is not yet integrated, the test responses are hard-coded for now.

Future steps will involve creating the main.go file, a Dockerfile, integrating Codecov for continuous testing, and connecting the API to the PostgreSQL database. The project repository is available for further details: https://www.php.cn/link/f72a23858b9865a40479a3ce3f16649e

The above is the detailed content of Building and Deploying a New API (Part 1). For more information, please follow other related articles on the PHP Chinese website!