Calling It REST Doesn't Make It REST

Common Response & Request Headers

Response Headers

Content-Length	Length of the message (without headers)
Content-Type	Media type of the entity-body sent to the recipient
Connection	Allows sender to specify options for a particular connection
Date	Current date and time according to the responder
ETag	Current value of the entity. Reflects changes only to object, not the metadata
Host	Specifies the Internet host and port number of response
Server	Information about the software used by the origin server

Request Headers

Accept	Type of content adequate for the response
Authorization	Information required for request authentication
Cache-Control	Directives that MUST be obeyed by all caching mechanisms
Content-Length	Length of the message (without headers)
Content-Type	Media type of the entity-body sent to the recipient
Date	Current date and time according to the requester
If-Match	Use with a method to make request conditional
If-None-Match	Use with a method to make request conditional
Host	Specifies the Internet host and port number of the resource requested
Server	Information about the software used by the origin server to handle the request

Caching lets an application reference a resource or composite resource later instead of re-fetching it, which reduces network traffic and latency and speeds up the user's response. If a resource is cacheable, give it an expiration.

Before You Ship

Data

• Is the data portable?
• Is the system context considered for a particular client?
• Are there developer groups this should be divided across?
• Is the resource's data cacheable?
• Are response formats specified using a schema?
• Confirmed: empty documents are never returned in case of an error — an error always gets a real, descriptive response.
• If this is meant for delivery or aggregation into existing websites: is it exposed as XML and consumed by HTML pages without a significant rework of the existing site architecture?

Project

• Is a risk assessment necessary?
• Are all stakeholders considered?
• Is there documentation for how to use the implementation?
• Has the rate of growth been anticipated?
• Have the effects of projected performance been considered?
• Is a growth trend available?
• Is the implementation timeline realistic?
• In an emergency, has maximum downtime been considered?
• Is there a fallback plan?
• Are there environment limitations for deployment?
• Has bandwidth been considered?
• Will the resource always return a response document?

The Actual REST Rules

This is the part most "REST APIs" quietly get wrong. Grouped by what they're actually checking, not as one undifferentiated list.

Resource Naming

• Resource names are plural nouns, not verbs — REST already defines the verbs: GET, POST, PUT, DELETE.
• The "/" in a URI expresses a parent-child relationship:

  /plural-noun/ID/plural-noun/ID

• Every resource has its own unique URI.
• The resource name is easy to recognize as a noun.
• The resource name is lowercase, with hyphens or underscores instead of spaces.
• Nothing gets added to the URI path just to describe the data — don't put metadata in the resource path.

Statelessness & HTTP Semantics

• The resource is stateless.
• The resource explicitly uses real HTTP actions — it's not REST wrapped around what are actually function calls.
• SOAP services aren't converted to REST with a one-to-one match; the underlying model has to actually change, not just the transport.
• The resource doesn't rely on server-side scripting technology to work.
• The query string is used only when necessary — check whether the parameter could pass through the message body instead.

Response Design

• Data structure stays the same every time — it doesn't vary by circumstance.
• Responses are never empty — even an error returns a descriptive response.
• Clients only receive the representation of the resource, not internal implementation detail.
• Errors use real HTTP status codes plus an application-specific error code.
• Every response includes a request ID for troubleshooting.
• The response transfers XML, JSON, or both — whichever fits the client.
• The response payload is simple, human-readable, and internally consistent.
• Content type matches what the client application actually needs.

Operations & Documentation

• The resource can integrate into other applications without rework.
• The resource is controllable by the caller/client.
• Clients can request a specific draft or version where that's relevant.
• The resource is fully documented.

Conclusion

None of these rules are exotic — most of them are things every REST tutorial mentions once, in passing, and most real APIs still violate at least a few of them by the time they ship. The fastest way to check yours: pick one endpoint and run it through the four rule groups above, in order. If it survives all four, it's actually REST — not just an API that happens to speak JSON.

Tyrone Showers