REST Web Service Notes

rest-web-service-notes.md

• 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.