REST, HTTP verbs, and the anatomy of a request

Three ways to see it

1. 1

   REST stands for Representational State Transfer, a name no one needs to memorise. What you do need is the working idea: every thing the system knows about is a resource, every resource has a URL, and you act on resources using a small set of verbs. A taxpayer is a resource at https://api.fbr.gov.pk/taxpayers/1234567. A bill is a resource at https://api.easypaisa.com.pk/bills/abcd. The URL identifies the thing. The verb describes what you want to do to it.

2. 2

   The verbs are few. GET reads a resource and returns it. POST creates a new one. PUT replaces an existing one in full. PATCH updates parts of an existing one. DELETE removes it. If FBR exposed a clean REST API, you would GET /taxpayers/1234567 to read a profile, POST /returns to submit a new tax return, PATCH /returns/abc to fix a number on an existing one, DELETE /returns/abc to withdraw it. Once you internalise the verbs, ninety per cent of REST is intuitive.

3. 3

   Every response carries a status code, a three-digit number that tells you what happened. 200 means success. 201 means a new thing was created. 400 means you sent something malformed, your fault. 401 means you are not authenticated. 403 means you are authenticated but not allowed. 404 means the resource does not exist. 429 means you sent too many requests too fast, slow down. 500 means the server broke, their fault. The codes are short because servers send millions per second. Learn the first digit and you can read any API log: 2 means good, 4 means client mistake, 5 means server mistake.

The why-tree

Try this with Claude

AI-edge prompt to try with Claude or ChatGPT: 'Draft a REST API for an FBR e-invoicing system. List five endpoints, each with the verb, URL, request shape in JSON, and expected response. Include one error case per endpoint with the right status code. Comments in Urdu.' Read the answer like a critic, not a believer.