XML rel and JSON hypermedia support

[nategood]

REST is about Hypermedia and self exposing APIs. The library should help pull those things out of responses when they exist.

[zackdouglas]

I understand XML rel, but how would this work with JSON? Is there a CoC for JSON hypermedia that I'm missing?

[nategood]

There is sort of a convention that some have coined as JSONH. Amundsen is generally on top of his REST/Hypermedia game. But also with JSON, just having the ability to notice a URI/URL in a response would be a nice. The library should promote HATEOS as much as possible. Treating URIs specially might help.

[zackdouglas]

Hmm.

Treating URIs specially

Sounds dangerous, particularly for poorly-coded APIs aiming to "play nice" with the '00's web scene. A la

GET https://example.com/resource/DELETE/1

shouldn't be exposed and iterated over "for convenience." This may be out of the scope, but if the Httpful consumer iterates over the provided links array calling HEAD, said server MAY act on that request as if it were DELETE!

[nategood]

Definitely a valid concern and maybe it's not ideal for any old URI. The library would not act on these URIs automatically, it would instead just help to expose them. I'm envisioning these features being great for REPL styling exploration of an API. So if you're inspecting relationships and URIs, then you're probably not going to hit that DELETE URI.

With poor APIs, the feature wouldn't be that compelling and probably not heavily used, but with better APIs focused more around REST and Hypermedia principles (which are springing up more and more frequently), the library could really flourish. I'm not aware of any other libraries that focus on the idea of HATEOS.

Example of using a REPL like phpsh to explore an API with Httpful (this is a very rough first concept here):

php> $nathan = Request::get('http://example.com/Nathan.xml')->send();
php> $nathan->showRelationships();
    array(
        'mother' => 'http://example.com/Kathleen.xml',
        'pets' => array(
            'http://example.com/Guinness.xml',
        ),
    )

It becomes really interesting when you turn these relationships into requests themselves

php> $mother = $nathan->get('mother')->send();

Just a thought. I've been really interested with the idea of RESTful design for a while and lately have really been interested in the idea of promoting HATEOS in APIs. Would be nice to see a library start to work in that direction.

[zackdouglas]

I think you're definitely on to something there. I don't know of a fluent interface to a HATEOS API.

I also agree that older, less compatible APIs shouldn't be exclusively catered to; my point was more of an anecdote than a veritable concern.

I like your rough draft, but I think there should be much care put into the chosen vocabulary to represent HATEOS functionality, as it seems to have recently gained occult following. The FOAF project may have useful knowledge on this point.

Personally, I'd like to see two public functions -- one for nouns, the other for verbs -- which are aliases to the same hypermedia data; it is my view that the library cannot accurately discern categorizations between the two, as these are application-level concepts. This would lend to the library's fluency, a la

$nathan->does('addpet')->send(array('name' => 'Wuff'));  // returns 200 OK
$nathan->knows('children')->get();  // returns 404 Not Found
$nathan->does('orphan')->send();   // returns 400 Bad Request

[nategood]

Been a while since I've checked out FOAF, OWL and Semantic Web stuff in general. I'll need to look through through it again soon. Sadly I think we're far from a true semantic web (in the sense of OWL, RDF, etc.) anytime soon.

Personally, I'd like to see two public functions -- one for nouns, the other for verbs

No verbs. It might work well in RDF but breaks RESTful principles. GET, PUT, POST, DELETE are your verbs in HTTP.

You might be on to something with does that would be more an OPTIONS call maybe to see what HTTP is allowed on a given resource.

[nategood]

HAL seems to be the closest this to XML rel. Maybe we start by only add support for this particular mime type.

[zackdouglas]

There are plenty of ways to convert XML to JSON, and HAL seems to be just one of those ways. At best, they provide a firm semantics to _rel, _links, _embedded, etc. At worst, they reserve these keys outside of application use. The translation that I'm most accustomed to - and arguably biased for - is to retain the structure as much as possible, and only reserve the "@attrs" property, which feels very unnatural to name ones object properties in an application but reasonable in a serialization context. (It brings to mind PHP's serialization format.)

[nategood]

The reason I brought up HAL is because it seems to be gaining a lot of traction amongst the "restafarian" folks. It along with Vendor MIME types seem to be the direction most of the better "hypermedia" driven libraries are going. I'm not familiar with the @attrs syntax you're referring to.

[nategood]

Closing this out in favor of a more flexible option. This can be better exposed in terms of registering custom parsers that handle special mime types (like HAL, Collection+JSON, XHTML, etc.). See #25.