Read REST APIs through resources and representations

Identify what the interface represents

A resource is the concept addressed by a URI; a representation is the data sent to describe or change its state. For an article resource, a JSON response might contain a title and publication date while the underlying application stores much more. Design the external representation for the consumer’s task.

Roy Fielding’s REST description includes constraints such as stateless interaction, a uniform interface, and explicit cacheability. A JSON response and a resource-shaped URL alone do not establish every REST constraint. Use the architectural ideas to ask better design questions.

Read an operation as a contract

For each operation, identify the target resource, method, request metadata, optional content, and expected response. Check whether the documentation explains both a successful interaction and the ways it can fail. Keep the meaning of an HTTP status distinct from the application data inside the response.

• Resources: Are identifiers stable and meaningful to consumers?
• Representations: Which fields can a client rely on, and how are optional values described?
• Interaction: Can the request be understood without hidden conversational context?
• Navigation: How does the client discover related resources or available next actions?

Consider a collection separately from an individual resource. A collection needs documented ordering and a way to traverse results. Avoid assuming that page size, sort order, or identifiers will behave like another provider’s API.

Design for change and failure

Write down how the interface handles missing resources, invalid fields, and attempts that lack permission. If clients may retry a request, inspect the method’s semantics and the service’s documented behavior before automating retries.

Make change management part of the contract. Removing a field that consumers require can be disruptive even when the URL stays the same. Preserve examples and compatibility checks around the operations your application depends on.

For an unfamiliar API, sketch one complete user task across its resources. That reveals whether the interface is understandable beyond a single successful request.

Continue to GET retrieval semantics and PUT replacement semantics for focused method guides. Use the broader API exploration workflow to turn your findings into a decision.