Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update hal.md

Browse Source
This commit is contained in:
Z
2017-06-26 09:47:40 +02:00
committed by GitHub
parent 5ea8243a5e
commit c54289bb44
1 changed files with 5 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
message/hal.md
View File

@@ -4,7 +4,7 @@ The [`application/hal+json`](http://stateless.co/hal_specification.html) (HAL) *
## Introduction to HAL
> _HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API._
This is an informal introduction for the HAL media type. For more details see [HAL - Hypertext Application Language Specification](http://stateless.co/hal_specification.html).
This document is an informal introduction to the HAL media type. For more details see [HAL - Hypertext Application Language Specification](http://stateless.co/hal_specification.html).
## Simple Document Example
The simplest Hal document looks like an empty JSON (it is an empty JSON!):
@@ -56,11 +56,11 @@ A more complex document example could be an "Order" resource that has a related
```
## Embedding Example
Let's assume there is an "Orders" resource which is a collection of all orders from different authors. Clearly there is the relation between the Orders resource and possibly many Order resources.
Let's assume there is an "Orders" resource which is a collection of all orders from different authors. There is the relation between the Orders resource and possibly many Order resources.
We could express this in the `_links` object using the `order` relation but sometimes it is practical to "embed" (fully or partially) related resources representations in the originating resource representation. For a scenario like this HAL offers the `_embedded` field.
We could express this in the `_links` object using the `order` relation, but sometimes it is practical to "embed" (entirely or partially) related resources representations in the originating resource representation. For a scenario like this HAL offers the `_embedded` field.
The `_embedded` field's object simply contains the related resources HAL representations:
The `_embedded` field's object just contains the related resources HAL representations:
```json
@@ -94,7 +94,7 @@ It is important to understand that embedded resource representation might be onl
The embedded resource representation should be used as a **convenience** function (e.g. to reduce the initial number of calls needed at application launch).
Where a full and up-to-date representation of a resource is needed the link relation should exercised (e.g. `GET /orders/2`).
Where a full and up-to-date representation of a resource is needed the link relation should exercise the affordance (e.g. `GET /orders/2`).
#### Real-world Examples