FDE Foundations · Module 4: Software Craft

Designing Small APIs

Customer-facing integration code lives for years. Small, boring APIs with strict validation, pagination, and versioning age well; clever ones do not.

11 min reading

Objectives

Design resource-oriented endpoints with validation at the boundary
Version and paginate from day one
Document the error contract, not just the happy path

Resource thinking

Name endpoints after resources and actions the customer recognizes: invoices, runs, exports. Keep the surface small: if the API has more than about ten endpoints, integration is getting harder for both sides. Prefer a few operations with clear inputs over many narrow ones.

Validate at the boundary

Parse and validate every input at the edge: types, lengths, ranges, formats, and permission checks in one place. Return structured errors with machine-readable codes so the customer's integration can branch on them. An error contract documented as carefully as the success contract is the difference between a support ticket and a log line.

Version and paginate early

Add a version prefix or header from the first release even if v1 is the only version. Renaming a field without versioning breaks customer code in ways that cost trust. Paginate every list endpoint; someone will ask for 100,000 rows in week two.

Document the truth

Write the API reference from the handler code or generate it, and include at least one error example per endpoint. Undocumented behavior becomes reverse-engineered behavior, and reverse-engineered integrations never break politely.

Quick check

An optional 2-3 question self-check. Answers never leave your device, are not stored, and never count toward any assessment.

Exercise

Design the API for a fictional invoice-status service: four endpoints, input validation rules, three error codes, and pagination on the list endpoint. Show one error response as JSON.

Pass criteria

Four endpoints with methods and paths, validation rules stated per field, error codes with meanings, a pagination scheme, and one JSON error example.