api-contract-firstlisted
Install: claude install-skill RBraga01/a-team
# API Contract First
## The Law
```
NO API IMPLEMENTATION WITHOUT A REVIEWED CONTRACT.
Writing endpoints before the contract is building to a spec that doesn't exist.
The contract IS the spec. Code that matches it is correct. Code that doesn't is wrong.
```
## When to Use
Use this skill before writing ANY of these:
- A new REST endpoint
- A new gRPC/protobuf service method
- A new GraphQL query, mutation, or subscription
- A new event schema (Kafka, SQS, webhooks)
- A new inter-service interface
## The Contract Process
### Step 1: Write the Contract
Choose the format that matches the project's stack:
**REST → OpenAPI 3.x**
```yaml
# docs/api/openapi.yaml
paths:
/orders:
post:
summary: Create a new order
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
'201':
description: Order created
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
components:
schemas:
CreateOrderRequest:
type: object
required: [userId, items]
properties:
userId:
type: string
format: uuid
items:
type: array
minItems: 1
items: