LearnThatStack Ace your next interview
Get Pro
Sign in
API Design · question
Question 49 of 92

What are the differences between API-first and code-first approaches?

intermediate Pro
← All API Design questions

The full answer covers the core mechanics, when this pattern wins, and the trade-offs interviewers most often probe. It includes a code sample. Read it once at your own pace, then try to recall the structure from memory before the interview. Pro also includes this question's interview lens - the likely follow-up probes and what you can say in the room.

Full answer + code samples + AI explanations

Unlock to read the complete answer for this premium question.

Browse free API Design questions → Unlock all · $10/mo
Guided practice for API Design One question at a time. Answer out loud, get graded, see what you missed.
Related concept

Documentation: the docs come from the spec, not a hand-written copy

Hand-written docs are a second copy of what the code does, and copies go out of date. A spec that generates the reference, clients and checks cannot go out of date.

For this question · chapter 2 of 3

2/3 One spec, many outputs
openapiOne spec, many outputswritten once, generated five timesgenerated5of 5outputs by hand0of 5a person writes4one fileopenapi.yamlthe only copy14 paths9 schemas22 examples11 errorsdesign firstwrite the file firstgenerate the handlerscode firstannotate the handlersemit the file from themgeneratedthe referenceevery path and fieldgenerated, never typedgeneratedclient SDKsfour languagesnone of them by handgenerateda mock serveranswers the examplesbefore you build itgeneratedrequest validationthe schema, at the edgerefuses what it forbidsgeneratedcontract testsCI compares the answersa dropped field failswhat a person still writesnothing below generates thesewhy you would call itthe auth guidewhat to do about each errormigration notesgeneration removes the drift. it does not write the explanation
openapiOne spec, many outputsgenerated5of 5outputs by hand0of 5one fileopenapi.yamlthe only copy14 paths9 schemas22 examples11 errorswritten first, or read out of the codegeneratedthe referenceevery path and fieldgeneratedclient SDKsfour languagesgenerateda mock serveranswers the examplesgeneratedrequest validationthe schema, at the edgegeneratedcontract testsCI compares the answerswhat a person still writes4why you would call itthe auth guidewhat to do about each errormigration notesgeneration cannot write the reasons

One spec, many outputs

  1. There are two ways to get one OpenAPI file. Write the file first and generate the handlers from it, or annotate the handlers and generate the file from them. Both ways produce the same file: 14 paths and 9 schemas, with 22 examples and 11 error codes. Five outputs could come from that file, but today a person types every one of them.
  2. The reference page is now an output of the spec file, so nobody types the page any more. Every path, field and example on the page comes from that file, so the page always matches the code. The difference from chapter one is in how the page is built. The page does not depend on anyone remembering to update it.
  3. In chapter one, a renamed field broke the partner's integration. Here the same spec file generates client libraries in four languages. Nobody writes those libraries by hand. So a field renamed in the spec changes in all four libraries on the next release. A build step now handles the exact change that broke the partner's integration.
  4. The examples in the spec file are enough for a mock server to answer requests. The mock server replies before the real endpoint exists. So your partner waits zero days and starts building on day one. The examples in a spec are also worth writing properly, because a server is going to return them.
  5. At the edge, the schema refuses any request with a field the schema does not define. The schema returns a 400 that names that field. So the spec file has a new role: the document that describes the API now enforces the API. A document you can run cannot be wrong without anyone noticing.
  6. Drift, where the code no longer matches the spec, now fails the build. In CI, contract tests use the spec file as the test fixture and check every response against the matching schema. So a handler that drops a field fails the build. Chapter one's bug would have failed the build on your machine the day the bug shipped, not nine days later in a stranger's ticket.
  7. Generation from the spec stops here, and this is the honest half of the answer. People write why to call this endpoint and how auth works end to end. They also write what to do about each error, and migration notes for a breaking change. An integrator reads these four documents first. Generation removes drift, but it does not write the explanation.
Chapter 2 · step 1 of 7

There are two ways to get one OpenAPI file. Write the file first and generate the handlers from it, or annotate the handlers and generate the file from them. Both ways produce the same file: 14 paths and 9 schemas, with 22 examples and 11 error codes. Five outputs could come from that file, but today a person types every one of them.

1 of 7 Use ← → or swipe See the concept: all 3 chapters in it

© LearnThatStack - diagrams may not be republished without permission.

Want a quick review of the fundamentals? See the API Design cheatsheet.

← Back to all API Design questions
Pro · $10/mo

74 of 92 API Design answers are in Pro.

Full answers, code samples, and AI explanations that go simpler or deeper. Cancel anytime.

  • Full answers + code
  • AI explanations, simpler or deeper
  • 1,000 AI credits / month
  • Cancel anytime
Get Pro → See plans & pricing →