REST

Published on: July 10, 2026

Most important commands to remember

curl -i URL — inspect a resource response and its headers.
jq — select fields from a JSON representation.

Commands and flags

Option or syntax	Meaning
`-i`	Include HTTP response headers.
`-fsS`	Fail on HTTP error statuses, hide progress, and retain error messages.
`--max-time 10`	Bound each request to ten seconds.
`\|`	Pipe curl’s body output into jq.
`jq '{name, full_name, private}'`	Build an object containing these three JSON fields.

The commands make two read-only requests for public repository metadata. A pipeline’s final status can hide curl’s failure; read errors from both commands.

The concepts that matter

1. REST is an architectural style

Representational State Transfer (REST) describes constraints for distributed systems, including a uniform interface, stateless communication, caching, and layers. It is not simply another name for any JSON API.

A resource is something identified and addressed, such as a repository or order. The server transfers a representation of its current state. That representation can be JSON, HTML, or another agreed format; the resource itself is not the serialized document.

2. Methods have shared meanings

An HTTP interface uses methods consistently rather than making clients infer intent from arbitrary action names. GET retrieves a representation. PUT replaces a target representation under the API’s rules. DELETE requests removal of the target association; POST commonly submits data for processing.

Safe methods are intended not to request state changes. Idempotent means repeated identical requests have the same intended effect, not necessarily identical response bytes. These properties matter for retries and intermediaries.

3. Stateless requests still operate on stored data

Statelessness means each request carries the context needed to understand it, rather than relying on an implicit conversational session stored by the server. The server can absolutely keep databases and resource state.

Authentication information, request parameters, and resource identifiers give context to each call. A service that stores an order is not violating statelessness merely because the order survives between requests.

4. A uniform interface makes interactions interpretable

Representations and metadata tell clients how to interpret responses, and links can describe available transitions. This hypermedia aspect is part of REST’s full architectural model, although many APIs called RESTful implement only part of it.

Status codes, validators, and content types let generic tools participate. Error bodies still need interpretation. A 200 JSON response is transport evidence, not proof that an API satisfies every REST constraint or that a requested business outcome is correct.

One small example

Optional: run the commands without credentials. They read a public repository through GitHub’s API and do not change it.

curl -i --max-time 10 https://api.github.com/repos/octocat/Hello-World
curl -fsS --max-time 10 https://api.github.com/repos/octocat/Hello-World | jq '{name, full_name, private}'

In the first response, read status, Content-Type, and any rate-limit or cache headers before the body. In the second, jq selects the repository name, full name, and private flag. This is a client-selected view, not a change to server state.

The public repository and API policy can change. A rate-limit or availability error is not a JSON parsing lesson; inspect curl’s error before treating missing output as missing data. These two independent reads also need not represent precisely the same instant.

No account, token, or local file is created, and no cleanup is required.

Keep this idea: REST organizes interactions around resources and a uniform interface; JSON alone does not make an API RESTful.