Is my JavaScript browser for hypermedia JSON APIs as RESTful as I think it is?

[Dave Gauer]

Hello,

I would genuinely appreciate some expert opinions regarding hm-json Browser, a JavaScript client for hypermedia JSON APIs:

https://bitbucket.org/ratfactor/hm-json-browser

(Documentation, the tiny source code, and most importantly, LIVE DEMO at the link above.)

I believe it passes the smell test for REST because it is:

1. Discoverable - the entire API can be traversed from a single starting URI
2. Fully self-documented - any HTTP method is supported (and the browser natively understands GET, PUT, POST, OPTIONS, and DELETE)
3. Encourages RESTful resources and a generality of interfaces (but being a client, can't actually enforce good RESTful design)
   

And though it's other features have nothing to do with REST, it also allows you to browse to templated URIs (level 1 variable expansion only), PUT and POST data through the browser, see titles and descriptions/instructions for the resources you are manipulating, and generally let you use the full range of HTTP's capabilities like I think we all wish Web browsers could.

I believe it will make any project which uses it extremely developer-friendly and I'm happy with it.

But I'm wondering if the browser (and my simplistic demo API) would be considered "real REST" by a true aficionado?   REST's "code on demand" constraint is explicitly optional, so I feel safe there.  But I don't address caching at all, and I'm wondering if that's enough to knock hm-json Browser out of the REST category altogether.  I could add caching, but it's really not a high priority for such a small tool and feels to me like it would be a pretty arbitrary requirement.

I have absolutely no interest in buzzwords and came to REST out of a true admiration for elegant API design.  If there are ways this could be improved, I would absolutely love to hear about them.

Thanks,

-Dave Gauer

[Mike Kelly]

Hi Dave,

Looks good. Have you seen the hal browser? That's pretty similar to this.

Did the "hypermedia" property come out of your work on the browser or
the other way around?

Cheers,
M

> --
> You received this message because you are subscribed to the Google Groups
> "API Craft" group.
> To unsubscribe from this group, send email to
> api-craft+...@googlegroups.com.
> Visit this group at http://groups.google.com/group/api-craft?hl=en.
>
>



--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[Dave Gauer]

Hi Mike,

Thanks, yes, I did indeed run across your HAL browser partway through.  In fact, I almost stopped my own work when I saw it because of the similarity, but was having too much fun to stop.  :-)

The thing that really stuck out for me with HAL was your concept of embedded resources.  They're a very clever idea and I like them a lot.   And forgive me for having not figured out the answer myself, but does HAL provide a way to describe all of the HTTP methods available for a given resource?  I didn't see that ability at the time and it was one of my own requirements for the actual product API for which I'm planning to use hm-json.

I do have one other question for you: have you gotten much feedback from strong REST purists about the RESTfulness of HAL?  Most of my reading has only turned up negative examples, API designs that don't meet full REST requirements for one reason or another.  It seems pretty rare that anyone comes forth and says, "this is real REST!" about anything.  Has Dr. Fielding put too much fear into everyone?

As for your chicken-and-egg question about the genesis of the "hypermedia" property: I imagined the browser first, but began writing examples of the hypermedia property before writing a single line of the browser code.  They both grew up together.  It's been a quick project, so I guess you could just say it happened all at once.

Thanks for your response and I have a ton of respect for what you've done with HAL.

-Dave

[Mike Kelly]

On Thu, Oct 18, 2012 at 6:09 PM, Dave Gauer <ratf...@gmail.com> wrote:
>
> Hi Mike,
>
> Thanks, yes, I did indeed run across your HAL browser partway through. In
> fact, I almost stopped my own work when I saw it because of the similarity,
> but was having too much fun to stop. :-)
>
> The thing that really stuck out for me with HAL was your concept of embedded
> resources. They're a very clever idea and I like them a lot. And forgive
> me for having not figured out the answer myself, but does HAL provide a way
> to describe all of the HTTP methods available for a given resource? I
> didn't see that ability at the time and it was one of my own requirements
> for the actual product API for which I'm planning to use hm-json.

I'm glad you like the embedded resources idea, it's something that not
everyone is keen on so it's nice to hear from someone else that thinks
its a good idea :)

No I didn't include http methods in HAL. You could add it in for your
use-case but it would be non-standard. Out of interest; what do you
need it for?

> I do have one other question for you: have you gotten much feedback from
> strong REST purists about the RESTfulness of HAL? Most of my reading has
> only turned up negative examples, API designs that don't meet full REST
> requirements for one reason or another. It seems pretty rare that anyone
> comes forth and says, "this is real REST!" about anything. Has Dr. Fielding
> put too much fear into everyone?

Fwiw, I've had an example hal+json API up for a while now and I'm yet
to be told it's not RESTful :)

http://haltalk.herokuapp.com/

There's also the google group which has ~120 people on it and again
nobody has questioned the RESTfulness of HAL there either:

https://groups.google.com/group/hal-discuss

> As for your chicken-and-egg question about the genesis of the "hypermedia"
> property: I imagined the browser first, but began writing examples of the
> hypermedia property before writing a single line of the browser code. They
> both grew up together. It's been a quick project, so I guess you could just
> say it happened all at once.

Interesting.. thanks for sharing that bit of back story. Let me know
how you get on, is this a public API?

Cheers,
M

[Dave Gauer]

(Yay, found the 'Quote original' option in the Google Groups web client and won't have to top-post like a noob anymore.  See response inline below.)

On Thursday, October 18, 2012 10:33:42 AM UTC-7, Mike Kelly wrote:

On Thu, Oct 18, 2012 at 6:09 PM, Dave Gauer <ratf...@gmail.com> wrote:
>
> Hi Mike,
>
> Thanks, yes, I did indeed run across your HAL browser partway through.  In
> fact, I almost stopped my own work when I saw it because of the similarity,
> but was having too much fun to stop.  :-)
>
> The thing that really stuck out for me with HAL was your concept of embedded
> resources.  They're a very clever idea and I like them a lot.   And forgive
> me for having not figured out the answer myself, but does HAL provide a way
> to describe all of the HTTP methods available for a given resource?  I
> didn't see that ability at the time and it was one of my own requirements
> for the actual product API for which I'm planning to use hm-json.

I'm glad you like the embedded resources idea, it's something that not
everyone is keen on so it's nice to hear from someone else that thinks
its a good idea :)

I really do.  It elegantly handles the problem of delivering a complete collection of lightweight resources without requiring that the client make a request for each one.  And I especially love the fact that it represents separate URI namespaces in a single document.  it's a really great idea and I definitely made a silent, "aha, that's clever!" when I saw it.

 

No I didn't include http methods in HAL. You could add it in for your
use-case but it would be non-standard. Out of interest; what do you
need it for?

Ultimately, this is all for a practical purpose: I'm a developer on a commercial web application and am in the early stages of designing its public-facing API.

When I first started thinking about having a browsable API, I originally imagined it as an XHTML-based interface.   I got that whole idea from the O'Reilly book "RESTful Web Services" - I just wrote a review last night: http://www.goodreads.com/review/show/436483456

But there were two problems with XHTML:

1. As a developer, I love the compact, expressiveness of JSON and I was having a hard time imagining not supporting JSON.

2. In reality, I might not actually be able to browse the XHTML API the way I wanted to because of the troubled browser support: http://www.quora.com/HTTP/Why-are-PUT-and-DELETE-no-longer-supported-in-HTML5-forms

So I wondered why I couldn't just create my own JavaScript browser that supported the full range of HTTP methods (since they work through XHR requests) and fulfill my dreams of browsing a complete API from the comfort of my mouse. :-)

Now to actually answer your question: In the API browser I envisioned, the description of all of a resource's supported methods has always been part of my discovery process.  My thought was that If it couldn't do that, I might as well just use XHTML and maybe tunnel the other methods through POST by setting a method override (as in method="PUT").

Honestly, if I had seen that HAL had the ability to assign a method to a link and that the HAL browser understood what to do with it, I probably would have scrapped hm-json and gone with it instead.

 

> I do have one other question for you: have you gotten much feedback from
> strong REST purists about the RESTfulness of HAL?  Most of my reading has
> only turned up negative examples, API designs that don't meet full REST
> requirements for one reason or another.  It seems pretty rare that anyone
> comes forth and says, "this is real REST!" about anything.  Has Dr. Fielding
> put too much fear into everyone?

Fwiw, I've had an example hal+json API up for a while now and I'm yet
to be told it's not RESTful :)

http://haltalk.herokuapp.com/

There's also the google group which has ~120 people on it and again
nobody has questioned the RESTfulness of HAL there either:

https://groups.google.com/group/hal-discuss

I guess a lack of negatives is pretty much a positive in the REST world.  Ha. :-)
I discovered your "haltalk" demo this morning when I saw your reply.  It's amazing how being able to play with the live animal makes the whole concept so much clearer.  Again, I think embedded resources really make the standard and the HAL Browser shine.

 

> As for your chicken-and-egg question about the genesis of the "hypermedia"
> property: I imagined the browser first, but began writing examples of the
> hypermedia property before writing a single line of the browser code.  They
> both grew up together.  It's been a quick project, so I guess you could just
> say it happened all at once.

Interesting.. thanks for sharing that bit of back story. Let me know
how you get on, is this a public API?

Thanks, Mike.  And I definitely wish HAL a long and prosperous future.  I really like the direction web services are taking away from insanely complicated XML-based stuff.

hm-json is absolutely public. I've put everything under the permissive MIT license and I welcome all feedback, suggestions, improvements, and pull requests. :-)

-Dave