Detailed Specification Sample - Customer List Retrieval API

tip

1. I created a PlantUML theme for Docusaurus because I wanted to write specifications like this!
2. Since it's text-based, almost everything can be written using ChatGPT. Super convenient.

Overview

1. This API retrieves a list of customer information.
2. It uses gRPC and is implemented based on connect-go.

Prerequisites

1. Authentication is required.
2. The user must have permission to view customer information.

CRUD

Operation: Read

1. Reference table: customers

Parameter Specification

{
  "userId": "string", // User ID
  "filter": "string", // Search condition (optional)
  "limit": "number", // Maximum number of records to retrieve (optional)
  "offset": "number" // Starting position for retrieval (optional)
}

Result Specification

{
  "customers": [
    {
      "id": "string", // Customer ID
      "name": "string", // Customer name
      "email": "string", // Email address
      "createdAt": "string" // Creation timestamp
    }
  ],
  "total": "number" // Total number of records
}

Sequence Diagram

Processing Details

[02]: Authentication

1. Verify the authentication information in the request.
2. If authentication fails, return an error and terminate processing.

[03]: Parameter Validation

1. Ensure userId is required.
2. Validate that limit and offset have appropriate values.
3. If validation fails, return an error and terminate processing.

[04]: Database Permission Check

1. Retrieve permissions based on userId.
2. If the user lacks permission, return an error and terminate processing.

[06]: Retrieve List from Database

1. Query the customers table based on filter, limit, and offset.
2. Retrieve the search results.

Convert to Result Format

1. Store customer information in the customers array.
2. Set total.

[08]: Return Result to Client