REST API Design Best Practices

Chapter 2 of 8 · 4 practices · 3 min · 4-question quiz

HTTP methods and their promises

What GET, POST, PUT, PATCH, DELETE and the new QUERY method promise to clients and intermediaries, and how to keep those promises.

Start: Respect what safe and idempotent mean

4 practices in this chapter

  1. 1Respect what safe and idempotent meanRFC 9110 gives each method properties that clients, proxies and caches rely on: Safe means the client does not request a state change: crawlers, prefetchers and link previews call GET freely…
  2. 2Create with POST to a collection and return 201 with LocationPOST /orders asks the server to create a new order and pick its id. On success, return: 201 Created; a Location header with the new resource's URL; the created resource in the body, so the…
  3. 3Use PUT to replace and PATCH to change part of a resourceThe difference matters because fields a client omits mean different things: PUT sends the complete new representation. A field left out is removed or reset to its default; PATCH sends only the…
  4. 4Consider QUERY for searches that do not fit in a URLComplex searches often outgrow a query string: long filter lists, nested conditions, or inputs that should not end up in logs. Teams then switch to POST /orders/search, which works but tells caches…

Check yourself on this chapter

4 questions, right here once you are signed in. Your progress is saved as you read.

Sign up for the quiz