Resource-centric
In a REST API data entities are expressed as resources (in relational databases they are rows of a table). A resource is anything that is enough important to have its own URL/ID. This could be a File, a Solar feature (Active Region), a Solar event (Flare) or the configuration vector of a neuronal network.
Linked data
Resources contain links to other resources.
API is self-documenting
Users and programs should be able to understand the data from their structure. Like a HTML web page that provides links to other pages, the REST API returns links to related resources. This can be achieved by following the HATEOAS principle.
Nested (embedded) resources vs. flat resources
There is an ongoing debate if resources should contain collections of nested resources or if everything should be kept flat and nested references should be defined by appropriate links.
JSON vs XML
Most big REST API providers (Google, Amazon, Microsoft, Twitter, Facebook, ...) switched from XML to JSON
Standards
Unfortunately there is no one-fits-all REST standard yet (despite 15 years of research in this field). But there are a couple of candidate technologies:
- HAL is a pretty simple media type to define links between resources and to embed resources into other resources (=nested resources).
HAL does not support actions. HAL seems to be the most used type at the moment. - JSON-API is the most recent standard and has gained a lot of momentum within the last months. It provides similar capabilities to HAL but unlike HAL it keeps the data graph flat: no nested collection are allowed. JSON-API focuses on minimizing the number of required server requests.
- Collection+JSON is mainly focused on collections. It specifies a couple of keywords to identify a collection but does not go beyond that: no actions, no links.
- Siren provides similar capabilities as HAL but adds actions.
JSON does not provide a type model. A couple of standards try to bridge this gap (by providing a so called JSON profile).
- JSON-LD is an official standard from the W3C. It adds certain keywords to mark collections or links in a JSON file.
Hydra adds actions to JSON-LD. Actions define what you can do with a resource. E.g. you can define templates on how to define a query or links to other resources. This makes the API self-documenting.
JSON-LD is particularly interesting to document existing APIs without breaking them. In this respect in can be considered as an alternative to WADL. - JSON Schema: schema definition for JSON. Probably being replaced by JSON-LD.
References