Re: [siren] Service Discovery and Custom Media Types (Forked: Proposal: Change rel and class values from string-separated token to arrays)

[Kevin Swiber]

Hey Pat,

Siren is intended to be used as a generic media type, like text/html.  Some folks do prefer app-specific media types or even types with more granularity (e.g., application/vnd.com.sun.cloud.Cloud+json).  There's nothing wrong with that, but like any design decision, there are trade-offs.  I went down this route for a while before settling on a more generic type (leading to Siren).

Some benefits of generic media types that I see: Having a generic media type means having reusable parsers.  Any API client for a Siren-powered hypermedia API can get a head start by understanding the Siren library (which is relatively simple).  It also means having a common, documented structure for hypermedia messages, hopefully providing a value of reduced client/server coupling and independent evolution.  Using application/vnd.siren+json will soon be more than just a casual recommendation.  It is going through the IANA media type registration process at the moment. 

I know you're a fan of Google Service Discovery documents, but I honestly haven't looked into it much.  Do you think Google Service Discovery documents could describe a service API that's built on top of Siren?  I would advocate including a link to a profile[2], possibly using "describedby" semantics.  If the "profile" link relation[3] becomes a standard, I think this would be my preference.  Curious to see your thoughts on this.

Thanks!

[1] http://www.amundsen.com/hypermedia/hfactor/

[2] http://gmpg.org/xmdp/

[3] http://tools.ietf.org/html/draft-wilde-profile-link-02

On Mon, Aug 6, 2012 at 2:03 PM, Pat Cappelaere <cappe...@gmail.com> wrote:

Kevin,

I am just kinda torn as I am trying to make sense out of this.

I like your approach but I am trying to look at it from a different perspective.

In my mind, hypermedia is not orthogonal to discovery but complementary.

I do see the importance of a good discovery document that documents the API in a machine readable format with matching schemas.

Once that document is published, the application needs to define/use a mime-type.

Your recommendation seems to be: application/vnd.siren+json.

But wouldn't it be more likely to be something like: 

application/vnd.myapp+json; describedby=myschema.rnc

The JSON format would still be Siren-like.. I think… may be with some additional simplification since a schema is also available…

I would like to get your feedback on this.

Many thanks,

Pat.

On Aug 6, 2012, at 11:35 AM, Kevin Swiber <ksw...@gmail.com> wrote:

Howdy, folks!

I've been doing some work creating a client and server implementation with Siren.  One pain point is constantly switching between string-separated token and arrays for rel and class values.  I'm proposing we just make them arrays in JSON and kill the hassle.

Here's what the new spec would look like: https://github.com/kevinswiber/siren/blob/string-to-array/README.md

And here's the Pull Request if you'd like to comment there and see the changes:  https://github.com/kevinswiber/siren/pull/1

Please let me know your feedback!  I think this will be a good win.

Thanks,

--
Kevin Swiber

Projects: https://github.com/kevinswiber
Twitter: @kevinswiber

--
You received this message because you are subscribed to the Google Groups "Siren Hypermedia" group.
To post to this group, send email to siren-hy...@googlegroups.com.
To unsubscribe from this group, send email to siren-hypermed...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
You received this message because you are subscribed to the Google Groups "Siren Hypermedia" group.
To post to this group, send email to siren-hy...@googlegroups.com.
To unsubscribe from this group, send email to siren-hypermed...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--
Kevin Swiber

Projects: https://github.com/kevinswiber
Twitter: @kevinswiber

[Pat Cappelaere]

Kevin,

I appreciate your hardwork on this.

My personal preference would be to avoid app specific media types.  It is not helpful as far as I can tell.

I do think that a Google Service Discovery Document can describe the full protocol that an app may require.

That protocol will require some Hypermedia capability, so we need something like Siren (or HAL for that matter)

The JSON schema could be derived from a Siren profile, I guess (assuming a JSON encoding)

I am not sure I truly understand [3], sorry!  but found a good discussion here: http://www.mnot.net/blog/2012/04/17/profiles

So I guess my vote, today, could be:

application/json; profile="http://example.com/orders"; describedby="schema.rnc"

:)

Does this help at all?

Pat.