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
Added a new collection of curied relations, described above.
Can be a single object or an array.
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}
]
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.
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 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 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?
{
"_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
}
- 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
- current implementations will not work due to prefix being explicitly added to link name
This seems overly complicated when you could just use conneg and redirects to achieve the same ends if you have these more complex requirements