# Your API contract will outlive the demo. Read Geewax in this order > Start with resources rather than endpoints, then spend your time on long-running operations, retries and versioning, where client integrations break most often. Original: https://fdetimes.net/en/books-courses/api-design-patterns-reading-order-fde/ When a forward deployed engineer leaves a client, what lasts longest is rarely the demo or the slides. It is the API contract: the names of the resources, how they are called, how errors are reported. The client's team will keep writing code against those decisions for years. That is why a book from 2021 still deserves a place on your desk. *API Design Patterns* by JJ Geewax was published by Manning in 2021. The publisher describes it as a collection of design principles for both internal and public-facing APIs. Manning says the book is written for developers building web and internal APIs in any language. An FDE has to connect their own system to the client's and design endpoints for the client, so that is close to a description of the job. The practical question is which parts to read before the first integration meeting. ## Start with resources, not endpoints Chapter 1, "Introduction to APIs", defines an API as the way computer systems interact with one another. It covers the basics and why they matter: interfaces, organising an API around resources, and what makes an API good. It sounds elementary, but this is the layer that decides the contract. Picture a client's internal API where `getOrder`, `fetch_customer` and `LoadInvoiceData` all live side by side. The API still works, but callers cannot guess what the next endpoint will be called. Thinking in resources first (orders, customers, invoices) lets you point out the problem without turning the conversation into a matter of taste. The summary of the book on System Design Space opens with a group of ideas it calls "API as a product and a contract". That grouping is the summariser's, not Manning's table of contents, but it captures the spirit: get the resource layer wrong and every pattern that follows has to patch around it. ## Long-running operations are where integrations break first Nicolas Fränkel's review on DEV Community confirms that the book includes a pattern for methods that do not return a result immediately. The System Design Space summary describes it as separating the start of an operation from the retrieval of its result, with clear status semantics. Imagine you are deploying a document-processing pipeline for an insurance company. Each batch takes several minutes, while the client's gateway drops connections after 30 seconds. If the endpoint waits until processing finishes before replying, the client sees an error even though the work is still running. The pattern's answer is to return an operation with a status straight away, which the client polls. Instead of an obscure error, the client gets something it can track. ## Ask about retries and versioning from day one Fränkel also confirms a chapter called "Request retrial", on algorithms for retrying requests safely. The summary recommends request identifiers and idempotency keys for important writes, together with a shared, structured error format. Take a hypothetical case: a client's ERP sends 1,000 create-order requests. Twenty time out on the network even though the server has already written them, and the ERP resends all 20. Without idempotency, the client ends up with 1,020 orders, 20 of them duplicates, and it is the accounts department that finds out, not you. With an idempotency key, the second call simply receives the result of the first. The final topic is the "Versioning and compatibility" chapter, which defines what compatibility means and sets out versioning strategies. The summary names backward-compatible change as the default strategy. Add an optional field and old clients keep working; make a field required and every script the client's team has written can break at once. **Key point:** The API contract you leave with a client will outlive your engagement. ## A reading order for people with a live project If you have an integration session next week, read chapter 1 first, then long-running operations, safe retries and finally versioning. The chapter titles above come from a review and a summary, so check the table of contents of the edition in your hands to find the matching sections. Leave the rest for a quieter moment. Fränkel recommends the book to every developer starting out with APIs, but notes that it falls short as a reference. For an FDE, that means not waiting for an incident before opening it in search of an answer. Read the sections above in advance, then write your own list of questions to take to the client. ## Two ways to waste the book The first mistake is jumping straight to retries or long-running operations and skipping chapter 1. Those patterns are all built on resources. If resources are named haphazardly, even the best pattern only makes the contract more tangled. The second mistake is retrofitting the book's patterns onto a client's API that is already in production. The System Design Space summary treats backward-compatible change as the default versioning strategy, and in that spirit, mass-renaming endpoints that people already use is a self-inflicted incident. Apply the patterns to what you are about to add, not to tear down what already works. ## Proving it on your CV On your CV, do not list the book. Describe the contract you left behind and how it held up, for example "designed an integration API with idempotency keys; no duplicate orders when the client enabled retries". When a job posting mentions "design APIs" or "build integrations", that is the story to tell in the interview. The point of reading is not to memorise patterns. It is to be the first person in the next meeting to ask: "What happens if this call is made twice?" **Try this week:** - Read chapter 1 in Manning's liveBook, then write down the resources of the API you are integrating with: what each is called and which resource it belongs to. - Pick one endpoint that writes data in your current project and ask: what happens if the client's system calls it a second time after a timeout? Record the answer in the design document. - List every operation that can run longer than the client's timeout, then sketch for each one a way to return a status the client can poll. ## Sources - [API Design Patterns (Manning Publications)](https://www.manning.com/books/api-design-patterns) - [API Design Patterns, Chapter 1: Introduction to APIs (Manning livebook)](https://livebook.manning.com/book/api-design-patterns/chapter-1) - [API Design Patterns (short summary), System Design Space](https://system-design.space/en/chapter/api-design-patterns-book) - [API Design Patterns (Nicolas Fränkel, DEV Community)](https://dev.to/nfrankel/api-design-patterns-5208) - [API Design Patterns, 1st edition (Pearson)](https://www.pearson.com/store/en-gb/p/api-design-patterns/P200000004835/9781617295850)