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

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."

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.

Prompts

Design a New 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."

Audit an Existing 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?"

Examples

The OpenAPI Contract (The Source of Truth)

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).

Resources

• API Evangelist Blog

• OpenAPI Specification

• Spectral (JSON/YAML Linter)