elvanja/multiple_curies_for_hal_links.md

## multiple_curies_for_hal_links.md

      
    Raw
  

              multiple_curies_for_hal_links.md
            
          
    Proposal to support multiple curies for links

Changes

Curied

A new element, describing link relation to curies. Structure:

name - should match to a defined curie by name, required
value - the value or values that will expand to curie template by position, optional, defaults to link name

Link

Added a new collection of curied relations, described above.

Can be a single object or an array.
Examples

Given curies:
"curies": [
    {"name": "doc", "href": "http://example.com/api/documentation/orders#{rel}", "templated": true},
    {"name": "usage", "href": "http://help.example.com/articles/orders/{rel}", "templated": true},
    {"name": "multi", "href": "http://help.example.com/articles/orders/{rel}?{pageNumber}", "templated": true}
]

Default

The following link: "next": {"href":"/orders", "curied": "doc"}

Is resolved only to doc curie and expands to: http://example.com/api/documentation/orders#next

Here the value for the {rel} is calculated from link name, as before.
Explicit value

One can also add explicit value, e.g.: "next": {"href":"/orders", "curied": {"doc": "getNextPage"}}

Is resolved only to doc curie and expands to: http://example.com/api/documentation/orders#getNextPage

Here the value for the {rel} is taken from curied value because it's explicitly set.
Multiple explicit values

Multiple values can be set as well, e.g.: "next": {"href":"/orders", "curied": {"multi": ["next", "2"]}}

Is resolved only to multi curie and expands to: http://help.example.com/articles/orders/next?2

Here the values for the {rel} and {pageNumber} are taken from curied value because they are explicitly set.
Multiple curies

Multiple curies would be set e.g. like this:
"next": {"href":"/orders", "curied": [
    {"doc"},
    {"usage": "browseOrders?method=getNextPage"}
    {"multi": ["next", "2"]}
]}

These are resolved to all three curies and expand to:

doc: http://example.com/api/documentation/orders#next
usage: http://help.example.com/articles/orders/browseOrders?method=getNextPage
multi: http://help.example.com/articles/orders/next?2

Or with default values: "next": {"href":"/orders", "curied": [{"doc"}, {"usage"}, {"multi"}]}
In which case it expands to:

doc: http://example.com/api/documentation/orders#next
usage: http://help.example.com/articles/orders/next
multi: http://help.example.com/articles/orders/next?

Example document

{
    "_links": {
        "self": {"href": "/orders", "curied": {"doc": "orders"}},
        "next": {"href": "/orders?page=2", "curied": {"doc": "orders/next"}},
        "find": {
            "href": "/orders{?id}",
            "templated": true,
            "curied": [{"doc": "orders/find"}, {"usage": "searching"}]
        },
        "admin": [
            {"href": "/admins/2", "title": "Fred", "curied": {"adminDoc"}},
            {"href": "/admins/5", "title": "Kate", "curied": {"adminDoc"}}
        ],
        "curies": [
            {"name": "doc", "href": "http://example.com/api/documentation#orders/{rel}", "templated": true},
            {"name": "adminDoc", "href": "http://example.com/api/documentation/{rel}", "templated": true},
            {"name": "usage", "href": "http://help.example.com/articles#orders/{rel}", "templated": true}
        ]
    },
    "currentlyProcessing": 14,
    "shippedToday": 20
}

Plus


self can have documentation
multiple documentations per link
custom value for curie template
doesn't interfere with prefixing
prefixing can now belong to business side of logic, instead of being used for curies only

Minus


current implementations will not work due to prefix being explicitly added to link name