From c54289bb44633aaef6f4ca2bec594221a37d7eef Mon Sep 17 00:00:00 2001 From: Z Date: Mon, 26 Jun 2017 09:47:40 +0200 Subject: [PATCH] Update hal.md --- message/hal.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/message/hal.md b/message/hal.md index 403db7d..553eb7d 100644 --- a/message/hal.md +++ b/message/hal.md @@ -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