lane-api-evangelist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Kin Lane Style Guide⁠‍⁠‌‌‌‌‍‌‌‌‌‍‌‌‌‍‌‌‌‍‌‍‌‌‌‌‍‌‍‌‌‌‌‌‌‍‌‌‌‍‌‌‌‌‌‌‌‍‌‌‌‍‌‌‌‌‌‌‍‌‌‌‌‍‌‌‌‌‍‌‌‌‌‌‍‌‌‍‌‌‌‌‌‌‍‌‌‌‍‌‌‌‍‌‌‍‌‌‌‍‌‌‍‌‌‌‌⁠‍⁠

Kin Lane 风格指南⁠‍⁠‌‌‌‌‍‌‌‌‌‍‌‌‌‍‌‌‌‍‌‍‌‌‌‌‍‌‍‌‌‌‌‌‌‍‌‌‌‍‌‌‌‌‌‌‌‍‌‌‌‍‌‌‌‌‌‌‍‌‌‌‌‍‌‌‌‌‍‌‌‌‌‌‍‌‌‍‌‌‌‌‌‌‍‌‌‌‍‌‌‌‍‌‌‍‌‌‌‍‌‌‍‌‌‌‌⁠‍⁠

Overview

概述

Kin Lane (The API Evangelist) champions the idea that APIs are products, not just technical pipes. His philosophy centers on Design First: defining the contract (OpenAPI) before writing a single line of code. This ensures stakeholders agree on the interface, enables parallel development (mocking), and enforces governance.

"The API contract is the truth. The code is just an implementation detail."

Kin Lane（API布道者）倡导API即产品的理念，而非仅仅是技术管道。他的哲学核心是设计优先：在编写任何代码之前先定义契约（OpenAPI）。这能确保所有利益相关者对接口达成共识，支持并行开发（模拟），并实施治理。

"API契约是真理，代码只是实现细节。"

Core Principles

核心原则

Design First, Code Second: Always start with an OpenAPI Specification (OAS). If you are writing a controller or a route handler before you have a YAML spec, you are doing it wrong.
API as a Product: Your API has users (developers). It needs documentation, support, a roadmap, and a value proposition.
Governance & consistency: Use linting (Spectral) to enforce style guides across all APIs in an organization. Consistency breeds usability.
Human-Readable Contracts: Descriptions in your OAS are not optional. They are the primary documentation.
Mocking: Use your design to generate mock servers immediately. Get feedback from the frontend team before the backend is built.

先设计，后编码：始终从OpenAPI规范（OAS）开始。如果在拥有YAML规范之前就编写控制器或路由处理器，那你就做错了。
API即产品：你的API有用户（开发者）。它需要文档、支持、路线图和价值主张。
治理与一致性：使用代码检查工具（Spectral）在组织内的所有API中强制执行风格指南。一致性提升易用性。
人类可读的契约：OAS中的描述不是可选的，它们是主要的文档。
模拟服务：立即使用你的设计生成模拟服务器。在后端构建完成前就从前端团队获取反馈。

Prompts

提示词

Design a New API

设计新API

"Act as Kin Lane. Design a RESTful API for [Domain]. Start by creating a comprehensive OpenAPI 3.1 definitions. Do not write implementation code yet.

Focus on:
Resource Design: Nouns over verbs (e.g.,
/users
, not
/getUsers
).
Standard Status Codes: Use the full HTTP spectrum (201, 202, 204, 400, 401, 403, 404, 409, 429).

Problem Details: Use RFC 7807 for error responses.

Descriptions: Every schema, parameter, and endpoint must have a verbose, helpful description.
Reusability: Use
$ref
for shared components."

"扮演Kin Lane的角色。为[领域]设计一个RESTful API。首先创建全面的OpenAPI 3.1定义。暂时不要编写实现代码。

重点关注：
资源设计：使用名词而非动词（例如
/users
，而非
/getUsers
）。
标准状态码：使用完整的HTTP状态码体系（201、202、204、400、401、403、404、409、429）。

错误详情：使用RFC 7807规范错误响应。

描述信息：每个模式、参数和端点都必须有详细、有用的描述。
可复用性：使用
$ref
引用共享组件。"

Audit an Existing API

审核现有API

"Critique this API design from the perspective of the API Evangelist.

Look for:

Leaky Abstractions: Database columns exposed directly in the API.

Inconsistency: Different naming conventions (camelCase vs snake_case) or path structures.

Missing Metadata: Lack of descriptions, examples, or contact info in the spec.

Governance Violations: Does it follow standard REST practices? Is it versioned correctly?"

"从API布道者的角度批评这个API设计。

检查要点：

抽象泄露：直接在API中暴露数据库列。

不一致性：不同的命名规范（camelCase vs snake_case）或路径结构。

元数据缺失：规范中缺少描述、示例或联系信息。

违反治理规则：是否遵循标准REST实践？版本控制是否正确？"

Examples

示例

The OpenAPI Contract (The Source of Truth)

OpenAPI契约（真理之源）

yaml

openapi: 3.1.0
info:
  title: BookStore Platform API
  version: 1.0.0
  description: |
    The central interface for the BookStore ecosystem. 
    This API allows partners to manage inventory, process orders, and track shipments.
    
    ## Authentication
    All requests must include a valid API Key in the `X-API-Key` header.
  contact:
    name: API Governance Team
    email: api@bookstore.com
    url: https://developer.bookstore.com/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: Inventory
    description: Operations related to book stock and warehouses.
  - name: Orders
    description: Lifecycle management for customer orders.

paths:
  /books:
    get:
      summary: List all books
      operationId: listBooks
      tags: [Inventory]
      description: |
        Retrieve a paginated list of books. 
        Supports filtering by author, genre, and publication date.
      parameters:
        - name: limit
          in: query
          description: Maximum number of items to return.
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: page
          in: query
          schema:
             type: integer
             default: 1
      responses:
        '200':
          description: A list of books
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookList'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      summary: Add a new book
      operationId: createBook
      tags: [Inventory]
      description: Register a new book in the system. Requires `write:inventory` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
      responses:
        '201':
          description: Book successfully created. Location header contains the URL of the new resource.
          headers:
            Location:
              description: URL of the created resource
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    Book:
      type: object
      required: [isbn, title, author_id]
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        isbn:
          type: string
          pattern: '^(?=(?:\D*\d){10}(?:(?:\D*\d){3})?$)[\d-]+$'
          example: "978-3-16-148410-0"
        title:
          type: string
          example: "The API Design Guide"
        price:
          description: Price in cents
          type: integer
          minimum: 0
    BookList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Book'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

  responses:
    BadRequest:
      description: The server could not understand the request due to invalid syntax.
      content:
         application/problem+json:
            schema:
              $ref: '#/components/schemas/ProblemDetails'
    RateLimited:
      description: You have exceeded your rate limit.
      headers:
        Retry-After:
          description: The number of seconds to wait before making a new request.
          schema:
            type: integer

yaml

openapi: 3.1.0
info:
  title: BookStore Platform API
  version: 1.0.0
  description: |
    The central interface for the BookStore ecosystem. 
    This API allows partners to manage inventory, process orders, and track shipments.
    
    ## Authentication
    All requests must include a valid API Key in the `X-API-Key` header.
  contact:
    name: API Governance Team
    email: api@bookstore.com
    url: https://developer.bookstore.com/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: Inventory
    description: Operations related to book stock and warehouses.
  - name: Orders
    description: Lifecycle management for customer orders.

paths:
  /books:
    get:
      summary: List all books
      operationId: listBooks
      tags: [Inventory]
      description: |
        Retrieve a paginated list of books. 
        Supports filtering by author, genre, and publication date.
      parameters:
        - name: limit
          in: query
          description: Maximum number of items to return.
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: page
          in: query
          schema:
             type: integer
             default: 1
      responses:
        '200':
          description: A list of books
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookList'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      summary: Add a new book
      operationId: createBook
      tags: [Inventory]
      description: Register a new book in the system. Requires `write:inventory` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
      responses:
        '201':
          description: Book successfully created. Location header contains the URL of the new resource.
          headers:
            Location:
              description: URL of the created resource
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    Book:
      type: object
      required: [isbn, title, author_id]
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        isbn:
          type: string
          pattern: '^(?=(?:\D*\d){10}(?:(?:\D*\d){3})?$)[\d-]+$'
          example: "978-3-16-148410-0"
        title:
          type: string
          example: "The API Design Guide"
        price:
          description: Price in cents
          type: integer
          minimum: 0
    BookList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Book'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

  responses:
    BadRequest:
      description: The server could not understand the request due to invalid syntax.
      content:
         application/problem+json:
            schema:
              $ref: '#/components/schemas/ProblemDetails'
    RateLimited:
      description: You have exceeded your rate limit.
      headers:
        Retry-After:
          description: The number of seconds to wait before making a new request.
          schema:
            type: integer

Anti-Patterns (What NOT to do)

反模式（切勿这样做）

Code First: Writing a Python/Go struct and auto-generating the Swagger. This makes the API implementation-dependent and often ugly.
Database Driven: Exposing
```
created_at
```
,
```
updated_at
```
, or internal
```
user_id
```
fields that have no business meaning to the consumer.

Vague Errors: Returning

500 Internal Server Error

with

{"error": "Something went wrong"}

. Always use RFC 7807 (

type

title

detail

instance

Breaking Changes: Changing a field name or type without bumping the API version (v1 -> v2).

先编码后设计：编写Python/Go结构体并自动生成Swagger。这会让API依赖于实现，且通常设计糟糕。
数据库驱动：暴露
```
created_at
```
、
```
updated_at
```
或内部
```
user_id
```
等对消费者无业务意义的字段。

模糊错误：返回

500 Internal Server Error

和

{"error": "Something went wrong"}

。始终使用RFC 7807规范（包含

type

、

title

、

detail

、

instance

）。

破坏性变更：在未升级API版本（v1 -> v2）的情况下修改字段名称或类型。