REST API Design Rulebook

Chapter 6. Client Concerns

Introduction

Any computer program can be a REST API’s client, but some examples include scripts loaded in web pages, handheld games, and business-critical applications running on server farms. REST APIs are designed to suit the needs of their client programs, whatever those needs may be.

This chapter provides a set of REST API design principles to address common client concerns. It concludes with a few rules to address the special needs of browser-based JavaScript clients.

Versioning

A REST API is composed of an assembly of interlinked resources: its resource model. The version of each resource is conveyed through its representational form and state.

Rule: New URIs should be used to introduce new concepts

A resource is a semantic model, like a thought about a thing. A resource’s representational form and state may change over time but the identifier must consistently address the same thought, which no other URI can identify. Furthermore, every character in a resource’s URI contributes to its identity. Therefore the version of a REST API, or any of its resources, typically should not be signified in a URI. For example, including a version indicator, like v2, in a URI conveys that the concept itself has multiple versions, which is usually not the intent.

A URI identifies a resource, independent of the version of its representational form and state. REST APIs should maintain a consistent mapping of its URIs to its conceptually constant resources. A REST API should ...