| name | lane-api-evangelist |
| description | Design APIs using Kin Lane's "API Evangelist" philosophy. Emphasizes Design-First (OpenAPI), governance, treating APIs as products, and the political/business impact of interfaces. Use when building public platforms or large-scale internal ecosystems. |
| tags | api, developer-experience, documentation, evangelism, sdk, onboarding, api-design, rest, community |
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.
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:
[]
[]
[, , ]
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
