The HAL example is misleading / incorrect

[weierophinney]

In this doc https://www.apigility.org/documentation/api-primer/halprimer
there is this example:

{
    "_links": {
        "self": {
            "href": "http://example.org/api/user/matthew"
        }
    },
    "id": "matthew",
    "name": "Matthew Weier O'Phinney",
    "_embedded": {
        "contacts": [
            {
                "_links": {
                    "self": {
                        "href": "http://example.org/api/user/mac_nibblet"
                    }
                },
                "id": "mac_nibblet",
                "name": "Antoine Hedgecock"
            },
            {
                "_links": {
                    "self": {
                        "href": "http://example.org/api/user/spiffyjr"
                    }
                },
                "id": "spiffyjr",
                "name": "Kyle Spraggs"
            }
        ],
        "website": {
            "_links": {
                "self": {
                    "href": "http://example.org/api/locations/mwop"
                }
            },
            "id": "mwop",
            "url": "http://www.mwop.net"
        },
    }
}

The "contacts" property should actually be "contact". It should also be a URI or a CURIE but I'm not too concerned about RFC5988 purity. I'm more concerned about the conceptual confusion caused by using the plural. The properties contained within the _embedded objects are link relation names. When you embed more than one object with the same link relation then you can use an array under the link relation property to hold a set of embedded objects. However, each object in that array is has the "contact" relation with the context resource. For the property inside the _embedded object to be "contacts" the self link should point to a resource which is a list of contacts. and the array should be inside the embedded object.

Unfortunately, this same error was in the original HAL specification for a while and led to confusion.

---

Originally posted by @darrelmiller at zfcampus/apigility-documentation#69