Glossary
REST API
A REST API exposes data as resources addressed by URL, acted on with the HTTP methods whose meanings are already fixed by the protocol, and reports the outcome through status codes rather than through a payload field. The term is used loosely: most APIs described as REST are HTTP APIs returning JSON, which is a narrower and more useful thing to say. What matters in an audit is not the label but whether the conventions are followed, because clients and caches depend on them.
The conventions clients rely on
A URL identifies a resource, not an action. The method says what is being done to it.
GET retrieves and changes nothing, which is what lets caches store the response and clients retry it safely.
POST creates or submits, PUT replaces, PATCH modifies, DELETE removes — each with a meaning the protocol already defines, so a client does not have to read documentation to know whether a retry is safe.
The status code is the result. An API returning 200 with an error inside the body breaks every client, proxy and monitor that reads the status.
Headers carry metadata: content type, caching, authentication. Putting those in the body works and discards everything the infrastructure already knows how to do.
Where the conventions get broken
An action encoded in the URL rather than in the method, which makes every operation a POST to a differently named path and removes any cache or retry semantics.
A 200 response carrying a failure. Monitoring sees a healthy API, clients that branch on status see success, and only code reading the body notices.
A GET that changes state, which a prefetching browser or a crawler will eventually trigger without anyone asking it to.
An error body with no stable machine-readable identifier, leaving clients to match on human-readable text that changes when someone improves the wording.
What an audit can observe
Which endpoints are publicly reachable and which refuse anonymous access, which is the first question about any API.
Whether each one is served over HTTPS, since a token sent to an HTTP endpoint is on the wire in clear.
The cross-origin policy, which decides which websites a browser will let read the response.
Whether the responses carry caching directives appropriate to what they return.
None of this establishes whether the design is good. It establishes whether the observable conventions are being followed.
The alternatives the term is contrasted with
A query-language API exposes a single endpoint and lets the client describe what it wants, which trades cacheability for flexibility.
A remote-procedure API models calls rather than resources, which is a better fit for actions that are not create-read-update-delete.
Neither is a defect. They are different trades, and an audit reports what is observable rather than preferring a style.
What is a defect in any of them is a response whose status contradicts its content.
Frequently asked questions
- Is any JSON-over-HTTP API a REST API?
- Loosely, that is how the term is used. Strictly, REST is a set of constraints about resources, methods and statelessness that many JSON APIs do not follow.
- Why does returning 200 on an error matter?
- Because everything between the client and the server reads the status: caches, proxies, monitors, retry logic. A 200 tells all of them the request succeeded.
- Is GET really guaranteed not to change anything?
- It is required not to by the specification, and browsers, crawlers and prefetchers assume it. A GET with side effects will eventually be triggered by something that was only looking.
Sources
Related
VeriFixScan crawls a site and applies its checks to every page it reaches, keeping the evidence behind each finding. Scanning one website is free.
Scan a website