- Only use a URL to reference a resource. A resource should never be referenced by some other bit of JSON by a simple identifier (id, oid, etc.)
- Use HAL to express relationships between resources. (http://stateless.co/hal_specification.html)
- If a resource appears in the _embedded section of a resource must also appear in the _links section of the resource.
- Items that appear in the _links section of a resource may also appear in the _embedded section of the resource.
- Use curies to simplifiy link relationship naming in resources.
- Use URI Templates to express optional parameters (generally query string parameters) for a resource.
- Define and publish a URI Template parameter table so clients know what the possible "fill-in-the-blank" fields are for URI templates.
REST Web Service Notes