Before You Begin
After you have exposed the base URIs for accessing the API, you must identify and first define the resources for it. By identifying the resources in the API, you can make the API more useful and easier to develop.
Each resource has its own unique URI. Defining URI patterns is important because URIs enable clients to directly access a resource.
For example, consider the case of our sample Phone Store API. Assume this API exposes a database that defines a list of phones and the features and specifications of each phone; wherein the list of phones is represented with the collection URI and the features of each phones is represented as an individual URI.
Collection Resource URI
/phones
Unique Resource URI
/phones/412456
We recommend that you follow these simple tips and guidelines for structuring the resource path (URI):
Short name URIs as much as possible - for example, prefer
/phones/412456 than
/phones/phone.php?phone_id=412456Straightforward and meaningful URIs to ease use of the resource -
/phones/412456 Consistent and predictable URIs patterns -
/phones/412456/features Simple and hierarchical URIs to represent the relationships - for example,
/phones /phones/412456 /phones/412456/features Nouns, not verbs - for example, plural nouns to represent list of things -
/phones; singular nouns to represent a particular thing -
/phones/412456 Hyphens, avoid spaces or underlines to improve and enhance aesthetic interaction with the resource - for example, prefer
/phones/412456 than
/phones/412456 Lower case, avoid mixed case and upper case to improve readability -
/phones/412456 than
/Phones/412456 Here are some common examples for our sample resource /phones:
/phones /phones/412456 /phones/412456?fields=(make,features,bodytype) /phones/412456/make /phones/search?q=(make,eq,apple) /phones/?make=apple&features=3g&price.min=44101 