Hal fixes

[maxsz]

I've made some changes to the library, so that we can work with it:

• Fixed new Swift warnings
• Added support for all HAL link properties (see https://tools.ietf.org/html/draft-kelly-json-hal-07#section-5.5)
• Fixed the test failures by using GET as the default method for transitions
• Updated the Podfile

[kylef]

Hi @maxsz, thanks for this pull request.

Would you be able to add some test cases for HAL link properties? I'd love to see test coverage here to ensure it's working correctly both now and in the future.

[maxsz]

Sure, I've added the tests 🍻. Also fixed the indentation (sorry!).

[maxsz]

Hey @kylef, I just wanted to re-open the discussion on this one. We're using these patches in production for quite some time now and I'd like to switch back to the official fork. Would you be willing to merge these? Then I'd take care of the conflicts and rebase it on the master branch...
Thanks!

[kylef]

Hi @maxsz I apologise for forgetting about this one. It's great to hear you are using this library.

I don't think attributes is the right place to put these HAL link properties and instead I think they should be moved as metadata.

There are a few resources in the character which contain more information on the desired design:

• https://github.com/the-hypermedia-project/charter/blob/master/reference/hypermedia-elements.md

The Python implementation has an implemented meta:

# Adding links
representor.links.add("self", "/customers/1")
representor.links.add("orders", "/customers/1/orders")

# Adding meta data to the resource
representor.meta.attributes.add("title", "Customer Details")
representor.meta.links.add("profile", "http://example.com/customer_profile")

# Adding meta data to the transition
transition.meta.links.add("deprecation", true)

The meta property contains a MetaItem which contains links and further attributes (https://github.com/the-hypermedia-project/representor-python/blob/master/representor/base.py#L126).

What do you think?

[maxsz]

According to the HAL standard the properties I've implemented belong to the link itself (see https://tools.ietf.org/html/draft-kelly-json-hal-07#section-5). Are you suggesting to add a meta property to the HTTPTransition struct to store the additional link properties? Or do you mean that we should use the metadata property of Representor to store the link object properties? In the latter case, I'm not sure if this would be convenient to use.

Here is an example of how the link properties from HAL link objects can be used:

var items = [CollectionItem]()
guard let collectionItems = representor.transitions["items"] else { /* ... */ }
// When iterating over the transitions for "items", use the name property to 
for collectionItem in collectionItems {
  // The "name" property is OPTIONAL. 
  // Its value MAY be used as a secondary key for selecting Link Objects
  // which share the same relation type. 
  // See https://tools.ietf.org/html/draft-kelly-json-hal-07#section-5.5
  guard let name = collectionItem.attributes["name"]?.value as? String else { continue }
  switch name {
    case "show": items.append(ShowItem(link: collectionItem.uri))
    // ...
    default: continue
  }
}

[kylef]

Transition metadata would be present on the transition. Resource metadata would be present on the resource.

templated, type, deprecation, name, profile title, hreflang would be present in the transition metadata (https://github.com/the-hypermedia-project/charter/blob/master/reference/hypermedia-elements.md#meta).

The attributes property on the transition are the expected attributes that you can use to follow the transition which HAL does not offer.

For example, in Siren you may have an Action as follows:

    {
      "name": "add-item",
      "title": "Add Item",
      "method": "POST",
      "href": "http://api.x.io/orders/42/items",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        { "name": "orderNumber", "type": "hidden", "value": "42" },
        { "name": "productCode", "type": "text" },
        { "name": "quantity", "type": "number" }
      ]
    }

title would be meta data on the transition, and the fields (orderNumber, productCode and quantity) are the attributes that you can send while performing the transition using the suggested content type application/x-www-form-urlencoded.