Every REST request is parametrized by a resource path that uniquely identifies a server-side resource. The REST identifiers are intended to allow clients to intuitively consume server-side resources.
The KijiREST API version is placed at the root of the resource path as the API entry point. Prefixing the resource path with the version in this manner results in graceful upgrades.
A Kiji cluster contains Kiji instances. To avoid name clashes with other direct child resources of the Kiji cluster resource (that is, with the version resource), all instances are grouped into a sub-collection named "instances". This resource serves as a namespace for all instances on this cluster.
To access a particular instance, request it as a child resource of the "instances" collection:
Every instance contains a collection named "tables". It serves as a namespace for all the tables in this instance.
To access a particular table, request it as a child resource of the "tables" collection:
This resource identifies an entity ID in a table. This endpoint is useful to return the hex representation of the HBase row key for a given Kiji entity ID.
Every table contains a collection named "rows".
Each row is identified by the ASCII encoding of its hexadecimal entity ID. Rows are the deepest identifiable resource.
Every KijiREST service is associated with a single Kiji cluster and the cluster may be considered the "root" resource (after the REST API version). The Kiji cluster's version (distinct from the KijiREST API version) is the endpoint within the cluster:
The File System Directory Tree Analogy
The Kiji resource chain induces a simple directory tree analogy where directories represent collections of resources.
For example, consider a cluster where there are two instances named "dev_instance" and "prod_instance". The prod_instance contains two tables, which are named "customers" and "songs":