REST and JSON APIs
Most public APIs you will meet call themselves "RESTful" and send JSON. Some truly follow REST; many are simply JSON over HTTP. Knowing the difference tells you what a caller can rely on, and what BookNook should promise.
The rule
REST: named resources, standard verbs, self-contained requests.
REST (Representational State Transfer) is an architectural style, not a protocol or a library. Its core ideas, in plain words:
- Resources with addresses: every thing worth talking about has a URL. Book 42 is
/v1/books/42; its loans are/v1/books/42/loans. - Representations: you never get "the book" itself, only a representation of it, usually JSON. The same resource could also be shown as CSV or XML.
- A uniform interface: every resource is handled with the same small set of HTTP methods and status codes, so learning one endpoint teaches you all of them.
- Stateless requests: each request carries all it needs, including credentials. Any server in a pool can answer it.
- Cacheable responses: responses say whether they may be reused, so caches can take load off the server.
- Layered system: the client cannot tell whether it is talking to the real server, a cache or a gateway, and does not need to.
The strictest form of REST adds HATEOAS ("hypermedia as the engine of application state"): responses include links to what you can do next, so clients follow links instead of building URLs by hand.
{
"id": 42,
"title": "The Hobbit",
"available": true,
"_links": {
"self": { "href": "/v1/books/42" },
"borrow": { "href": "/v1/loans", "method": "POST" }
}
}When the book is on loan, the borrow link disappears. Few public APIs go this far, but the idea is useful.
A simple JSON API keeps HTTP and JSON but drops some of these rules. It might expose POST /api/borrowBook and return 200 for everything. It works, but every endpoint has its own habits, and generic tools such as caches and retry libraries cannot help.
The shortcut
Test any endpoint against three questions: Is the thing a noun in the URL? Is the action a standard method? Could any server answer this request alone?
Noun in the URL?
No.
renewLoanis a verb, and the loan's identity is hidden in the query.
The trap is thinking JSON makes an API RESTful. REST is about resources, methods and statelessness; JSON is just the format.
Drills
Answer fast — trust the rule.
Which URL follows REST's "resources with addresses" idea?
What does "stateless" mean for a REST API?
A book response contains a borrow link only when the book is available. Which REST idea is this?
An API sends JSON but uses POST /api/deleteMember and returns 200 for every outcome. What is the fairest label?
Remember
- REST: named resources, standard verbs, self-contained requests.
- Shortcut: noun in the URL, standard method, any server can answer.
- Trap: JSON does not make an API RESTful; verbs in URLs usually mean it is not.