Why this matters
Strong examples and SDK-friendly design turn your API from “understandable” into “adoptable.” As an API Engineer, your daily work includes enabling quick integrations, reducing support tickets, and ensuring autogenerated SDKs are predictable. Clear, runnable examples shorten time-to-first-call and raise integration success.
- Real tasks you will face: drafting request/response examples for new endpoints, shaping OpenAPI specs for SDK generation, keeping error shapes consistent, and reviewing naming for language friendliness.
- Outcome: developers can copy, paste, and succeed without guesswork.
Who this is for
- Backend and platform engineers exposing REST/HTTP APIs
- API product engineers writing documentation and OpenAPI specs
- Developer experience (DX) engineers maintaining SDKs
Prerequisites
- Basic HTTP knowledge (methods, status codes, headers)
- JSON data structures and common types
- Intro-level OpenAPI understanding (paths, schemas, operationId)
Concept explained simply
Examples act like a map. They show where to start, which fields matter, and what success/failure looks like. SDK-friendly design is about shaping endpoints and specs so code generators and hand-written SDKs produce intuitive, type-safe, and consistent client methods.
Mental model
Think of your API spec as the single source of truth. From it, you generate docs, SDKs, and tests. If your examples are realistic and your shapes are consistent, everything built on top inherits that clarity.
DX goals checklist (open)
- Time-to-first-success under 5 minutes with a curl example
- Operation names read like functions (unique operationId)
- Errors are structured and documented with sample payloads
- Pagination, filtering, and idempotency are consistent
- Examples include minimal and full payloads
SDK-friendly principles
- Naming consistency: choose camelCase or snake_case; do not mix.
- Stable, explicit types: document enums, nullable, formats (date-time ISO 8601, uuid).
- Predictable pagination: same fields (e.g., page, perPage, nextPage, total) or cursor-based with nextCursor.
- Error contract: code, message, details; same shape across endpoints.
- Idempotency for unsafe writes: support Idempotency-Key header for POST/PUT where appropriate.
- Versioning: surface version in URL or header; keep examples versioned.
- OpenAPI hygiene: unique operationId, tags, summary, description, requestBody schemas, examples, default and error responses.
- SDK generation friendliness: avoid ambiguous polymorphism unless clearly discriminated; avoid reserved keywords (class, default) in field names.
- Copy-pasteable examples: include curl and at least one language snippet; use clear placeholders like YOUR_API_KEY and RESOURCE_ID.
Worked examples
Example 1: Minimal vs. full request
Endpoint: POST /payments
Minimal request (quick start):
POST /payments
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"amount": 1999,
"currency": "USD",
"source": "tok_visa"
}
Response:
201 Created
Content-Type: application/json
{
"id": "pay_9rXw3",
"status": "succeeded",
"amount": 1999,
"currency": "USD",
"createdAt": "2023-08-01T12:45:00Z"
}
Full request (advanced fields):
POST /payments
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: 7f1b0e2d-03e2-4ef7-a6e9-6a0c5a1bb333
Content-Type: application/json
{
"amount": 1999,
"currency": "USD",
"source": "tok_visa",
"capture": true,
"metadata": {"orderId": "ord_12345"},
"description": "Pro subscription August"
}
Example 2: Consistent error shape
Failed request due to invalid amount:
422 Unprocessable Entity
Content-Type: application/json
{
"error": {
"code": "amount_too_low",
"message": "Minimum amount is 50 (in minor units).",
"details": {"min": 50, "provided": 10}
}
}
Note the same top-level "error" object used across the API.
Example 3: Cursor pagination
Endpoint: GET /payments?limit=3
200 OK
X-RateLimit-Remaining: 98
Content-Type: application/json
{
"data": [
{"id": "pay_1", "amount": 500, "currency": "USD"},
{"id": "pay_2", "amount": 1000, "currency": "USD"},
{"id": "pay_3", "amount": 1500, "currency": "USD"}
],
"nextCursor": "c3RhdGU6cGF5XzM=",
"hasMore": true
}
Next page:
GET /payments?limit=3&cursor=c3RhdGU6cGF5XzM=
OpenAPI snippet pattern (for reference)
paths:
/payments:
post:
operationId: createPayment
summary: Create a payment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
examples:
minimal:
value:
amount: 1999
currency: USD
source: tok_visa
full:
value:
amount: 1999
currency: USD
source: tok_visa
capture: true
metadata: { orderId: ord_12345 }
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
examples:
success:
value:
id: pay_9rXw3
status: succeeded
amount: 1999
currency: USD
createdAt: 2023-08-01T12:45:00Z
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
amountTooLow:
value:
error:
code: amount_too_low
message: Minimum amount is 50 (in minor units).
details: { min: 50, provided: 10 }
Design checklist
- Examples are copy-pasteable with placeholders like YOUR_API_KEY
- Provide minimal and full examples for complex endpoints
- Use consistent error envelope: error.code, error.message, error.details
- Include idempotency examples for POST/PUT when relevant
- Document pagination with both first and next-page examples
- Ensure unique, verb-like operationId values for all operations
- Specify formats (uuid, date-time, email) and enums in schemas
- Avoid reserved keywords in field names; keep casing consistent
Exercises
Work through the two exercises below. They mirror the auto-graded tasks. Your quick test results will be saved if you are logged in; otherwise they are temporary for this session.
- Exercise ex1: Write minimal and full examples for POST /payments, plus a 422 error payload. See full instructions in the exercise card.
- Exercise ex2: Make a spec snippet SDK-friendly (add operationId, fix casing, unify error shape, and add examples).
- [ ] I verified that request and response examples compile to valid JSON
- [ ] I used consistent casing and timestamps in ISO 8601
- [ ] I included both success and error examples
- [ ] I added or checked operationId uniqueness
Common mistakes and self-check
- Mixing casing styles (camelCase here, snake_case there). Self-check: scan schemas; fix to a single style.
- Examples that cannot run (missing headers, wrong content type). Self-check: try the curl yourself with placeholders.
- Unstable error shapes. Self-check: compare errors across 3 endpoints; they should match.
- Omitting operationId. Self-check: ensure every operation has a unique, meaningful operationId.
- Ambiguous pagination. Self-check: verify that nextCursor or nextPage is always present/absent consistently with hasMore.
Debugging tips
- Validate JSON with a formatter before publishing.
- Lint your OpenAPI schema; ensure examples conform to schemas.
- Add a tiny smoke test script that performs your quick-start example.
Practical projects
- Refactor one existing endpoint to include minimal/full examples, error examples, and idempotency guidance.
- Create a mini OpenAPI spec (3 endpoints) and generate an SDK; adjust fields until the SDK feels idiomatic.
- Draft a “5-minute quick start” using your examples and test it with a teammate.
Learning path
- Start: write runnable curl examples for two endpoints
- Add: minimal and full payloads, plus standard error
- Harden: unify pagination, idempotency, and operationId
- Validate: schema lint + sample SDK generation
Mini challenge
Pick any GET list endpoint you own. In 15 minutes, add:
- One first-page example and one next-page example
- Rate-limit header example
- Consistent hasMore and nextCursor fields
Run your examples to ensure they are copy-pasteable.
Next steps
- Complete the exercises below and then take the quick test.
- Apply the checklist to one production endpoint this week.
Quick Test
Anyone can take the test. Progress is saved for logged-in users.