copyleftdev 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
$reffor 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 internaluser_idfields that have no business meaning to the consumer. - Vague Errors: Returning
500 Internal Server Errorwith{"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).