RESTful API
design & development
in Baltimore

Most API projects document what was built. The endpoints get written first, someone adds a Postman collection or a page of notes once the shape has settled, and the documentation drifts further from reality with every change nobody remembers to write down. Spec-first design flips that order: the specification, written in a format such as OpenAPI, comes before a single line of endpoint code, and the code is built to match it rather than the other way round.

Writing the paths, request bodies, and response schemas first forces decisions that are easy to skip when coding directly. What does a missing field return. What shape does an error take. Which fields are optional on creation but required on update. Answering these questions on paper, before any implementation exists, is far cheaper than discovering the gaps once two teams are already relying on inconsistent behavior in production.

A written specification becomes something a front-end team, a mobile team, or an outside integrator can work against immediately, without waiting for a single endpoint to be finished. Tools can build a mock server directly. It returns realistic sample responses that match the agreed schema. Front-end work starts the same day the contract is settled, running in parallel with backend work instead of queued behind it.

The specification becomes more than documentation once it exists. It becomes a source of truth. Request validation middleware can be generated straight from the schema, rejecting a malformed request before it reaches business logic. Client libraries follow the same path. That saves integrators from writing an HTTP wrapper by hand, and cuts the chance a client misreads a field type.

Reviewing a specification catches problems a code review misses. A pull request that only touches implementation is reviewed for correctness within that one endpoint, in isolation from everything around it. A specification reviewed on its own is judged against the whole surface of the API instead. A reviewer can spot an inconsistent naming pattern, a duplicated concept, or a response shape that does not match a similar endpoint added the month before.

Keeping the specification and the running code aligned takes deliberate effort, not good intentions alone. A contract test suite, run in the same pipeline as the rest of the build, can compare live responses against the schema and fail the build the moment the two disagree. Without that check, a specification quietly becomes fiction within a few sprints. Everyone reverts to reading the actual code to find out what an endpoint really returns.

None of this suits every project. A small internal script calling two endpoints for a one-off data pull gains little from a formal specification and its tooling. Writing the two requests directly and moving on is the more sensible choice there. The approach earns its cost on an API meant to be integrated against by more than one team, or kept stable for longer than a single sprint.

The long-term payoff shows up well after launch, when a new integrator asks how a particular endpoint behaves. Pointing to a specification that has stayed accurate saves a support conversation. It often saves a misunderstanding that would otherwise surface as a bug report weeks later. Documentation written after the fact rarely earns that kind of trust, because everyone involved remembers at least one place where it was already out of date.