Hypermedia and genericness

146 views
Skip to first unread message

Steve Klabnik

unread,
Sep 19, 2012, 4:13:31 AM9/19/12
to api-...@googlegroups.com
I wrote a little comment here:
http://practicingruby.com/articles/81#comments that I thought you all
might find useful/interesting as well. Reproduced below:

Hey there!

Here's one of the big things you're missing: your JSON API _does_ have
some sort of schema, semantics, and other things. But rather than
actually describing them, in your API, it's basically ad-hoc. You say
"This is JSON, and by the way, here's all this other stuff you have to
know." We call this 'out-of-band information.' A hypermedia API has
all of this information published in one place.

What does this grant us? Generic clients. Here's an illuminating
example: Fundamentally, Twitter and RSS are the same thing, right? A
published list of content that updates itself every so often. But, if
I write a Twitter client, I cannot use that client to also connect to
identi.ca: they have different APIs. This happens because they're both
RPC-style; the functions aren't named the same thing, they don't take
the same inputs. That's why, in generic-minded clients, you see a
'ports and adapters' based architecture. They wrap the different
interfaces to expose a unified one.

However, if you write an RSS client, you can use it on any site that
exposes RSS. That's because it emits data that's compliant with the
standard. This generic-ness even allows mash-up stuff to be possible;
think about Google Reader. It's essentially an API client that allows
you to hit multiple services and mash them all up in one unified
timeline.

Also note that this is reduced coupling. In the Twitter example,
there's a high degree of coupling involved in the client and the
server. The client _must_ know the exact stuff that's going on in
order to connect to the client. The RSS stuff is loosely coupled; the
client needs to know nothing specific about my blog, other than it
emits `application/atom+xml` or `application/rss+xml`.

Plus, clients that don't understand all of RSS know how to understand
some parts, but not others. So, I can write an XSLT script, and it
will work on any RSS feed, because all RSS is also XML. This 'dumb
client' doesn't understand the full type, but knows enough to work. In
addition, 'smart clients' that understand
[PubSubHubbub](http://code.google.com/p/pubsubhubbub/) can grab an RSS
feed and do even _more_, since they understand _additional_ semantics
on top of the type.

> I'm still waiting to be convinced the complexity of the client of a hypermedia API is balanced by it's advantages.

It's funny how perspective works. Is a formalized document like
[this](http://www.ietf.org/rfc/rfc5005.txt) more or less complex than
an ad-hoc, constantly changing document like
[this](https://dev.twitter.com/docs)? How am I notified of changes to
the Twitter API? Why must my old clients break when new stuff comes
out?

> I'd want to make it as simple and ubiquitous as possible. Right now, to me, that's a JSON API.

Sure thing. We have different goals: you're trying to get people to
pay any attention to you, I'm trying to move the state of the art...
forward. In a way. Also backwards, in a way. This stuff is _old_. It
_works_. It has already stood the test of time. But because we have a
fashion-driven culture, (and also in the pursuit of profit rather than
working software, but that's another tangent), we've thrown away
time-tested ideas. I am currently on a quest to educate people that we
can have a _better_ world than the 'simple and ubiquitous' one we have
now, which, from my perspective, is massively complex and horribly
broken. Then again, as Fielding says,

> REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. Unfortunately, **people are fairly good at short-term design, and usually awful at long-term design. Most don’t think they need to design past the current release.** There are more than a few software methodologies that portray any long-term thinking as wrong-headed, ivory tower design (which it can be if it isn’t motivated by real requirements).
>
> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-724

Emphasis mine.

Pat Cappelaere

unread,
Sep 19, 2012, 8:04:18 AM9/19/12
to api-...@googlegroups.com
Steve,

Trying to push the state of the art is a noble goal. But is it going to be achieved by educating developers in using custom media-types?

There is a need for ubiquitous media-types (rss, atom, png…), no question.
Now imagine talking to your IPhone, SIRI makes a query on your behalf and retrieves 100+ results from 100+ web apps, all using a different media-type. Bummer! This becomes quickly a tower of babel problem.

In most cases, I think I would rather see developers use plain JSON and add a profile/schema information to describe the interface. Now that would be progress. If used enough, that "Jargon" would naturally get promoted to an official language or Lingua Franca. It takes time. Let's not go too quick and do it in a way that promotes interoperability. This is still Hypermedia by the way. There are still links, controls but with contextual information available online. Now this can support longevity.

Thanks,
Pat.
> --
> 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.
>
>

Steve Klabnik

unread,
Sep 19, 2012, 8:06:30 AM9/19/12
to api-...@googlegroups.com
> But is it going to be achieved by educating developers in using custom media-types?

Absolutely not. We need a balance between custom types and generic
ones; but I've found that I can more easily explain 'here's building a
custom type' and then 'you probably don't want to do that; choose an
existing type where possible' to people afterwards.

> I think I would rather see developers use plain JSON and add a profile/schema information to describe the interface.

My current explanations all explain things as application/json plus
draft-wilde-profile-link-03.

Pat Cappelaere

unread,
Sep 19, 2012, 8:16:27 AM9/19/12
to api-...@googlegroups.com
Steve,
Really? SIRI would say: "what does that mean?", skip!
Pat.

Steve Klabnik

unread,
Sep 19, 2012, 8:18:09 AM9/19/12
to api-...@googlegroups.com
"Hey, check it out, there's this profile thing. We'll talk about it
later. You can see we're serving JSON!"

**shows API**

"So we have this thing called a media type. JSON is super generic. We
flavor it with a link, which points to a doc that describes our
particular flavor of JSON!"

Nobody has ever been confused by this.

Pat Cappelaere

unread,
Sep 19, 2012, 8:25:38 AM9/19/12
to api-...@googlegroups.com
Steve,
Sorry but you are tap dancing here.

This does not help SIRI one bit:
application/json + draft-wilde-profile-link-03

Now if you were to say:

application/json; profile="http://example.com/wildeschema#subtype"

now SIRI may have a chance.

Pat.

Steve Klabnik

unread,
Sep 19, 2012, 8:34:20 AM9/19/12
to api-...@googlegroups.com
No, I just didn't expect you to nit pick over a sentence. On a list
named 'api-craft', I will use terms of art like
'draft-wilde-profile-link-03.' In a presentation or discussion I'll
use very descriptive sentences. You're being insanely obtuse for no
reason.

Also, application/json does not take any parameters, so that is
invalid. You have to use a Link header. Since we're being mega
pedantic in this thread.

Pat Cappelaere

unread,
Sep 19, 2012, 8:44:49 AM9/19/12
to api-...@googlegroups.com
Steve,

Since you want to educate developers, you may want to be very specific and help us get it right.
This is not a small topic that you can simply wave off.
If you think that it is better to use a Link header, please explain to us why it is so.

You seemed to be describing content negotiation.
It is usually done with an Accept header.

In that case, SIRI might understand this:
Accept: application+json; profile="http://example.com/myschema#output2"

It is very explicit. It points to an online schema and to a particular relevant fragment.

[I am not trying to be pedantic here. This is actually very critical to get it right for us]

Cheers.
Pat.

Steve Klabnik

unread,
Sep 19, 2012, 8:55:41 AM9/19/12
to api-...@googlegroups.com
> Since you want to educate developers, you may want to be very specific and help us get it right.
> This is not a small topic that you can simply wave off.

Sure, but I was discussing "when I explain this to people," not "the
previous email I sent to the list."

> If you think that it is better to use a Link header, please explain to us why it is so.

Because you _cannot_ provide a 'profile' parameter to the
application/json media type. RFC4627 states ' Required parameters:
n/a\nOptional parameters: n/a' and so

> Accept: application+json; profile="http://example.com/myschema#output2"

Is illegal.

draft-wilde-profile-link-03 describes a link relation. Therefore, we
need a link. According to RFC5988, a Link header lets us link to
something and provide a link relation.

In the slides that I refer to, I have

GET / HTTP/1.1
Host: www.example.com

HTTP/1.1 200 OK
Content-Type: application/json
Link: <http://www.example.com/profile>; rel="profile"

{"some":"json"}

... with fuller JSON based on the specific thing I'm talking about.

Pat Cappelaere

unread,
Sep 19, 2012, 9:52:29 AM9/19/12
to api-...@googlegroups.com
Steve,

Thanks. That's interesting … I did not know that RFC5988 had been accepted.

I guess the debate is still raging on whether or not it is a good idea.
http://www.mnot.net/blog/2012/04/17/profiles

I am just curious to see how many people will do this.
Now if that information is in your API discovery service document, this becomes unnecessary and can be removed from every transaction (therefore removing the chatter).
Wouldn't that be a better state of the art?

Pat.

On Sep 19, 2012, at 8:55 AM, Steve Klabnik <st...@steveklabnik.com> wrote:

>> If you think that it is better to use a Link header, please explain to us why it is so.
>
> Because you _cannot_ provide a 'profile' parameter to the
> application/json media type. RFC4627 states ' Required parameters:
> n/a\nOptional parameters: n/a' and so
>
>> Accept: application+json; profile="http://example.com/myschema#output2"
>
> Is illegal.
>
> draft-wilde-profile-link-03 describes a link relation. Therefore, we
> need a link. According to RFC5988, a Link header lets us link to
> something and provide a link relation.
>
> In the slides that I refer to, I have
>
> GET / HTTP/1.1
> Host: www.example.com
>
> HTTP/1.1 200 OK
> Content-Type: application/json
> Link: <http://www.example.com/profile>; rel="profile"
>
> {"some":"json"}
>
> ... with fuller JSON based on the specific thing I'm talking about.
>

Steve Klabnik

unread,
Sep 19, 2012, 9:55:32 AM9/19/12
to api-...@googlegroups.com
> Wouldn't that be a better state of the art?

I don't have time to reply fully at the moment, but I strongly dislike
service documents. In an RPC style, they make total sense, but from a
REST or Hypermedia perspective, they don't add much and restrict
flexibility.

I believe I've posted to this list at length before.

Steve Klabnik

unread,
Sep 19, 2012, 9:58:35 AM9/19/12
to api-...@googlegroups.com
Oh, and 'chatter' is only significant if you go over a tcp packet
boundary. I find that trying to optimize bytes off of http headers
generally isn't worth it.

Pat Cappelaere

unread,
Sep 19, 2012, 10:19:20 AM9/19/12
to api-...@googlegroups.com
or 3G?
Not worth optimizing?

Kevin Swiber

unread,
Sep 19, 2012, 11:11:30 AM9/19/12
to api-...@googlegroups.com
I am a fan of the profile link relation, but I have an issue with this example:

GET / HTTP/1.1
Accept: application/json; q=1.0, application/xml; q=0.8

200 OK
Content-Type: application/json
Link: <http://x.io/profile/hotdog>; rel="profile"

The content negotiation in this example is only for basic over-the-wire formats that contain no domain semantics or processing information.  Knowing a profile will come back in the response is information communicated out-of-band.  Sure, the response could be some form of hypermedia… but maybe not.

Profile links, in my opinion, are more fitting as mixins for an existing rich media type much like HTML and hCard.

I'd rather see:

GET / HTTP/1.1
Accept: application/vnd.siren+json; q=1.0, text/html; q=0.8

200 OK
Content-Type: application/vnd.siren+json
Link <http://x.io/profile/hotdog>; rel="profile"

Where, in this case, we're mixing a hotdog into Siren.

{
  "properties": {},
  "entities": [],
  "actions": [],
  "hotdog": {
    "delicious": "yes",
    "nutritious": "no",
    "substance": "tofu"
    "toppings": ["relish", "CATSUP", "Sriracha sauce"]
  },
  "links": []
}

Using profiles to completely define the semantics of the response is not a win, in my opinion.  Using profiles to add extensions to a semantically rich media type, on the other hand, is pretty rocking'.

I like hotdogs. 

-- 
Kevin Swiber
Sent with Sparrow

Matthew Bishop

unread,
Sep 19, 2012, 11:41:28 AM9/19/12
to api-...@googlegroups.com
The more I listen to this (highly repetitious) topic, he more I realize we need both generic content types like Siren as well as business-level types. One thing I like about Siren is that the Content-Type header describes the generic format of Siren, while inside there is a field called 'class' that can hold the business type.

The header is for the http client to use to deserialize the data stream and the class field is for the app client to use to determine just what kind of representation it is. This has two benefits:

1. Clients to not have to try to catch the HTTP headers to grok the business type. This is good because they may not be using http at all. Rest is an architectural style that lives outside of http.

2. Shared business types need to have a variety of transport mechanisms and formats. Some notable examples around real-world concepts like geospatial, date time and addresses exist as formats in various formats. Another example is the UBL which is used by the EU for intrabusiness transactions.

In the end the client has to be able to identify the business type and locate them in the data they receive. This is harder than it sounds because theses shared types are rarely defined in the same format as the client. The server needs to communicate the format separately so the client knows where to look for the specific properties.


Pat Cappelaere

unread,
Sep 19, 2012, 11:47:43 AM9/19/12
to api-...@googlegroups.com
Kevin,

So you are saying that "http://x.io/profile/hotdog" contain the schema definition for that particular resource representation?

Should that resource itself point back to its schema definition? like in the self link?
or _profile or kind attribute?

kind could be a partial to your custom schema
  
I guess you have a class concept in Siren but it is an array for some reason.

Steve Klabnik

unread,
Sep 19, 2012, 12:07:10 PM9/19/12
to api-...@googlegroups.com
I have never found the ~50 bytes worth it, no.

Sent from my iPod.

Pat Cappelaere

unread,
Sep 19, 2012, 12:16:16 PM9/19/12
to api-...@googlegroups.com
How long does you IPhone last on one charge?
Pat.

Steve Klabnik

unread,
Sep 20, 2012, 12:29:53 AM9/20/12
to api-...@googlegroups.com
No idea, it's never lasted less than a day.

Pat Cappelaere

unread,
Sep 20, 2012, 8:10:57 AM9/20/12
to api-...@googlegroups.com
Steve,

I am sorry for having been so short in my responses but here is my train of thoughts based on Sam Ramji's presentation (and many others) at REST FEST 2012 (http://vimeo.com/49609651).
Tomorrow's users are not going to be humans and humans will be more likely to use a phone for their web interactions.
I agree that a few bytes here and there are not a big deal at some level but they do represent a cost at the end of the day and this on each side (client and server) depending on the number of users and transactions. I think that we should be more and more aware of this and try to save when we can. It is always a trade off… and this will make our phones last longer…
Thanks for sharing.
Pat.


On Sep 20, 2012, at 12:29 AM, Steve Klabnik <st...@steveklabnik.com> wrote:

> No idea, it's never lasted less than a day.
>

Mike Kelly

unread,
Sep 20, 2012, 8:31:15 AM9/20/12
to api-...@googlegroups.com
fwiw, I think effort to address that particular issue is better off
spent on things like pushing browser vendors to improve the
sophistication of their caches. e.g. supporting stale-if-error and
friends, standardising an API for cache allocation, etc.

Cheers,
M
--
Mike

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

Steve Klabnik

unread,
Sep 20, 2012, 8:52:54 AM9/20/12
to api-...@googlegroups.com
Right. My point is that unless you can demonstrate to me that shaving
50 bytes off of a header actually increases battery time, we're
playing in the realm of theory here. I've never been able to
demonstrate this actually being an improvement.

Premature optimization is the root of all evil. And in this case, we
don't even know if it's an optimization!

Luke Stokes

unread,
Sep 25, 2012, 12:57:41 AM9/25/12
to api-...@googlegroups.com
I've really enjoyed this thread. Thank you to everyone who participated. I'm missing RESTfest already. :)

We posted a blog tonight along these same lines: http://www.foxycart.com/blog/the-hypermedia-debate

We're considering Siren for many of the same reasons Matt mentioned. I know everyone's busy, but if you're interested in hashing out this debate for a very specific problem domain (ecommerce), I'd really value your comments on that post.

I'm hoping to build an API that will help the community of API developers. Something people can look at for inspiration and ideas. There may not be a single "right" way to do everything, but if we can find enough best practices in one place, that could go a long way. I know it's what I was looking for 9 months ago.

Mike Kelly

unread,
Sep 25, 2012, 3:30:30 AM9/25/12
to api-...@googlegroups.com
Hi Luke,

I'd be interested to see how you felt the various options in terms of
generic media types played off against one another. Specifically your
thoughts for/against HAL relative to others.

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.
>
>



Enrique Amodeo

unread,
Sep 25, 2012, 4:20:15 AM9/25/12
to api-...@googlegroups.com
Hi, I was watching this thread with interest and a thought came to me: we are doing too much design up front without enough empiric information. If we aren't realistic we are going to end with something like XHTML & XForms, an specification that nobody cares.

By now I dare say the consensus is that Hypemedia APIs are good, but we have a lot of doubts and different approach on the specifics on how to do hypermedias APIs. I think this is because we don't have enough Hypermedia APIs in production on the real world. People are still catching up with the concept and usually think in CRUD terms.

Why don't just simply evangelize developers with the Hypermedia API concept and let them figure the specific details out? After all they have specific problems, so they should engineer specific solutions. We don't know yet if there is a single good way to all the scenarios. Until we don't have a lot of Hypermedia APIs on the wild we cannot use facts to guide a useful generic approach. With the lessons learned in the practice we can decide things like:

a) Is better to use web linking or embed the links? Is it really important?
b) If it is better to embed links, what is the best way to do it?
c) Custom media type vs. Profiles 
d) Should we use an existing vocabulary like microformat (http://microformats.org/) or microdata schemas (http://www.schema.org/docs/gs.html) or perhaps is better an XMLSchema like approach
e) Only JSON APIs or XML/HTML? Isn't it better to support multimedia APIs?

I expect that after a somewhat chaotic proliferation of approaches, the best ones will survive. Then it could be feasible to merge their best practice to achieve some kind of standard, or at least, a best practices thing.

Cheers,
Enrique Amodeo

Andrei Neculau

unread,
Sep 25, 2012, 6:00:41 AM9/25/12
to api-...@googlegroups.com
+1 Enrique

empiric information (which reminds me of some academic papers I'm reading on REST, not empirical, but I wonder how many actually are aware of them), and even complete implementations.
If there was an abstract, yet complete implementation of how to design and consume an API "style", I don't think there would be so much fuss. Some of the issues you listed would be non-issues (eg. custom media types vs profiles), or they would become complementary options (eg. use both web linking and embed links).

Somebody said on another thread that API designers don't develop enough against their own APIs, and I think there's a seed of truth and a lesson in that.

Mike Kelly

unread,
Sep 25, 2012, 6:24:04 AM9/25/12
to api-...@googlegroups.com
We don't need more theories or papers, we just need people to design
media types and provide examples of their use. Like mamund did with
maze+xml, and I did with haltalk:

http://amundsen.com/media-types/maze/
http://haltalk.herokuapp.com/

Also, it's not as simple as API designers developing against their own
APIs.. I'm pretty sure most designers worth their metal will at least
write tests and/or put a client library together. Yet that so doesn't
actually address the real issue of a distributed application, which is
that people you don't know and won't have chance to talk to will write
code that interfaces with (and couples to) your application. The
challenge of designing an evolvable distributed application like an
API is in managing those clients and how they couple to your
application. An API designer writing clients against an API they wrote
is not going to indicate whether the system meets that challenge. The
way you do that is through careful, principled design of your
interface (w/ hypermedia this is essentially media types and link
relations) which places clients under constraints and leads them in a
particular direction.

This is why more features in your media type is not necessarily a good
thing. The more features you add (forms, typing via profiles, etc),
the bigger the potential surface of your application clients will
couple to, and the higher the cost of managing change in your
application. So if you are looking at something like HAL and wondering
why XYZ feature is not included, it may well be for that reason - and
if you're looking at other media types that have 'additional features'
you should think carefully about whether the additional surface area
is worth the benefit. More is not always better.

In the end though these are all just design considerations, which
means it is largely subjective and since every API has different
context, objectives and business drivers there can't be any "right"
answer.

Andrei Neculau

unread,
Sep 25, 2012, 8:22:37 AM9/25/12
to api-...@googlegroups.com
We don't need more theories or papers, we just need people to design 
media types and provide examples of their use.

academic papers are not just theories, nor just papers - some abide the "publish or perish" and publish toilet paper, but some don't. I prefer to put my faith in the latter.

http://ws-rest.org/2012/proc/a2-7-strauch.pdf for example is rather enlightening (at least to me) - I've been diving into REST for a while, and I've never heard of RPC tunneling as a good (if intermediary) thing when talking about REST API

I do agree though that the power of example is big, and that is a great complement, if not even the starting point for research.
But saying that it's enough for everyone to dive head-on... and not have some scientific way of at least analyzing the results.. I just cannot share your view there. Sorry.

In the end though these are all just design considerations, which 
means it is largely subjective and since every API has different 
context, objectives and business drivers there can't be any "right" 
answer. 

Design considerations have consequences with a higher or lower impact.
Not knowing the consequences, doesn't make the design subjective. It makes the choice of a design over the other subjective.
You seem to put the shape, size, width, material of a wheel (let's have it square, made out of rocks!) on the same design level with the color of a chassis. Even the latter might have consequences - say painting a car with chrome silver mirroring paint could lower the visibility of the other cars on a sunny day (just a stupid example).

Mike Kelly

unread,
Sep 25, 2012, 8:49:37 AM9/25/12
to api-...@googlegroups.com
On Tue, Sep 25, 2012 at 1:22 PM, Andrei Neculau
<andrei....@gmail.com> wrote:
>> We don't need more theories or papers, we just need people to design
>> media types and provide examples of their use.
>
>
> academic papers are not just theories, nor just papers - some abide the
> "publish or perish" and publish toilet paper, but some don't. I prefer to
> put my faith in the latter.
>
> http://ws-rest.org/2012/proc/a2-7-strauch.pdf for example is rather
> enlightening (at least to me) - I've been diving into REST for a while, and
> I've never heard of RPC tunneling as a good (if intermediary) thing when
> talking about REST API
>
> I do agree though that the power of example is big, and that is a great
> complement, if not even the starting point for research.
> But saying that it's enough for everyone to dive head-on... and not have
> some scientific way of at least analyzing the results.. I just cannot share
> your view there. Sorry.

No problem

Cheers,
M

Luke Stokes

unread,
Sep 25, 2012, 9:49:27 AM9/25/12
to api-...@googlegroups.com
On Tue, Sep 25, 2012 at 2:30 AM, Mike Kelly <mikeke...@gmail.com> wrote:
Hi Luke,

I'd be interested to see how you felt the various options in terms of
generic media types played off against one another. Specifically your
thoughts for/against HAL relative to others.


Hey Mike. Funny you should ask because our current output (some examples can be seen here, though they will all change: http://wiki.foxycart.com/v/0.0.0/api) is very similar to HAL. We used your hypermedia format, as an example. At various times, we've leaned toward each one. Meeting Mike Amundsen at RESTfest got me thinking more about CJ (and generic media types in general). Our current leaning towards Siren also resulted in some good conversations with Kevin Swiber (thanks for commenting, Kevin!).

We like how Siren provides actions because our problem domain involves exposing much of our system so hosted content management platforms can re-create our entire admin within their interface. Lot's of CRUD, input forms, etc. If we build out those actions correctly, it might save them some time and allow them to have forms that change overtime as we add new features and fields. Your B.5. FAQ seems to indicate you'll be adding something similar to HAL in the future as well.

I also like how Siren tries to model the web linking spec. That helped me understand that spec better.

We haven't yet made a decision other than our current custom format probably isn't the best way to go. I greatly appreciate the comments already submitted on the post and am going to dive into them right now.
 
Cheers,
M
 
On Tue, Sep 25, 2012 at 5:57 AM, Luke Stokes <luke....@gmail.com> wrote:
> I've really enjoyed this thread. Thank you to everyone who participated. I'm missing RESTfest already. :)
>
> We posted a blog tonight along these same lines: http://www.foxycart.com/blog/the-hypermedia-debate
>
> We're considering Siren for many of the same reasons Matt mentioned. I know everyone's busy, but if you're interested in hashing out this debate for a very specific problem domain (ecommerce), I'd really value your comments on that post.
>
> I'm hoping to build an API that will help the community of API developers. Something people can look at for inspiration and ideas. There may not be a single "right" way to do everything, but if we can find enough best practices in one place, that could go a long way. I know it's what I was looking for 9 months ago.
>
> --
> 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.
>
>



--
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.





--
Luke Stokes

Pat Cappelaere

unread,
Sep 25, 2012, 11:35:31 AM9/25/12
to api-...@googlegroups.com
Mike,

With the advent of Open Graph, Action Links and Semantic web, I need a media that can help me describe those action links, relate entities from an Open Graph, a media that can help me define actions/activities that could be performed on behalf of my users in terms defined in that same graph.
I need to be able to generate stories based on those activities so they show up on our users timelines and news feeds.  I also need to relate back to a JSON-Schema to avoid any need for out-of-band information and reduce API chatter.

So here we go, since you asked :)


Thanks,
Pat.

Mike Kelly

unread,
Sep 25, 2012, 11:47:49 AM9/25/12
to api-...@googlegroups.com
Hi Luke,

On Tue, Sep 25, 2012 at 2:49 PM, Luke Stokes <luke....@gmail.com> wrote:
> We like how Siren provides actions because our problem domain involves
> exposing much of our system so hosted content management platforms can
> re-create our entire admin within their interface. Lot's of CRUD, input
> forms, etc. If we build out those actions correctly, it might save them some
> time and allow them to have forms that change overtime as we add new
> features and fields.

Thanks for this, it leaves me with a few more questions:

Have you discussed this with potential implementors at the other end?
Is their front-end going to call out your API for any pages including
these forms?
Is there a reason that these forms could not be served directly as
HTML (i.e. either as text/html or encoded in a string inside a JSON
response)?

> Your B.5. FAQ seems to indicate you'll be adding
> something similar to HAL in the future as well.

Yeah, if/when that happens that would be a new type rather than a
change to hal+json.

Cheers,
M

Luke Stokes

unread,
Sep 25, 2012, 12:01:20 PM9/25/12
to api-...@googlegroups.com
On Tuesday, September 25, 2012 10:47:52 AM UTC-5, Mike Kelly wrote:
Hi Luke,

On Tue, Sep 25, 2012 at 2:49 PM, Luke Stokes <luke....@gmail.com> wrote:
> We like how Siren provides actions because our problem domain involves
> exposing much of our system so hosted content management platforms can
> re-create our entire admin within their interface. Lot's of CRUD, input
> forms, etc. If we build out those actions correctly, it might save them some
> time and allow them to have forms that change overtime as we add new
> features and fields.

Thanks for this, it leaves me with a few more questions:

Have you discussed this with potential implementors at the other end?
Is their front-end going to call out your API for any pages including
these forms?

We've discussed it briefly, yes. The initial feedback has been very positive. I'm currently thinking about it as a time-saver option for them along with a nice way to discover new functionality at run time. They can build out their own forms or they can dynamically pull the core pieces from us. Taking this to another level, my business partner is interested in letting them customize the forms as full Twig templates. That raises some additional concerns to me, but it's something we're exploring. Which leads to your next question:
 
Is there a reason that these forms could not be served directly as
HTML (i.e. either as text/html or encoded in a string inside a JSON
response)?

We may move that direction, but from what I've seen of form frameworks, everyone does things a little differently. As much as I'd like to believe there is a single semantic way for how form labels and controls should be organized, everyone seems to do things in their own way with their own classes and ids. If we provide the whole form layout as is, they may not have the flexibility they need.

Our current ecommerce system injects form controls by replacing ^^cart^^ and ^^checkout^^ as an example. We tried to follow the CSS Zen Garden approach and let people style as needed. For the most part that works, but we still ran into situations where people needed something different (which is why our last release now supports Twig). With HTML5 and mobile forms, I'm not sure locking them into a specific HTML payload will provide the flexibility some of our users want.

As I said, though, we're definitely exploring it.

As as I just learned in #rest, apparently there's a large debate as to whether forms are a good or bad thing, so hopefully we didn't just open another can. :) I'll do some more research on that before we make a decision.

Mike Kelly

unread,
Sep 25, 2012, 12:07:00 PM9/25/12
to api-...@googlegroups.com
On Tue, Sep 25, 2012 at 4:35 PM, Pat Cappelaere <cappe...@gmail.com> wrote:
> Mike,
>
> With the advent of Open Graph, Action Links and Semantic web, I need a media
> that can help me describe those action links, relate entities from an Open
> Graph, a media that can help me define actions/activities that could be
> performed on behalf of my users in terms defined in that same graph.

Provided you can represent action links entities, and other resources
in your system with JSON then you can use hal+json for that and it
will also cover you for relating the entities together.

You will have to establish what link relations you need for the
various application flows required between your resources.

e.g.

*entry-point* > find-by-user-id > stories (get to a given users stories)
*entry-point* > action-links (get a list of your apps action links)

> I also need to relate back to a
> JSON-Schema to avoid any need for out-of-band information and reduce API
> chatter.

Not sure about this, never seems necessary to me.

Cheers,
M

Mike Kelly

unread,
Sep 25, 2012, 12:32:23 PM9/25/12
to api-...@googlegroups.com
On Tue, Sep 25, 2012 at 5:01 PM, Luke Stokes <luke....@gmail.com> wrote:
> On Tuesday, September 25, 2012 10:47:52 AM UTC-5, Mike Kelly wrote:
>>
>> Hi Luke,
>>
>> On Tue, Sep 25, 2012 at 2:49 PM, Luke Stokes <luke....@gmail.com> wrote:
>> > We like how Siren provides actions because our problem domain involves
>> > exposing much of our system so hosted content management platforms can
>> > re-create our entire admin within their interface. Lot's of CRUD, input
>> > forms, etc. If we build out those actions correctly, it might save them
>> > some
>> > time and allow them to have forms that change overtime as we add new
>> > features and fields.
>>
>> Thanks for this, it leaves me with a few more questions:
>>
>> Have you discussed this with potential implementors at the other end?
>> Is their front-end going to call out your API for any pages including
>> these forms?
>
>
> We've discussed it briefly, yes. The initial feedback has been very
> positive. I'm currently thinking about it as a time-saver option for them
> along with a nice way to discover new functionality at run time. They can
> build out their own forms or they can dynamically pull the core pieces from
> us.

Ok so if your consumers short circuit your forms then you won't be
gaining any evolvability benefits, since your API will always need to
support the lowest common denominator that is non-form-aware, right?

Are you concerned you that you may be cluttering up your API responses
with these form controls and making them more difficult to read? It is
possible for a formless media type to be time-saving through browsers
that present documentation in-line (the hal browser does this) - you
coud actually have a dummy form in the rel documentation where devs
could input test data.

> Taking this to another level, my business partner is interested in
> letting them customize the forms as full Twig templates. That raises some
> additional concerns to me, but it's something we're exploring. Which leads
> to your next question:

To clarify; these twig templates are for use in a hosted version of
your web app, not relating to the API per se?

>>
>> Is there a reason that these forms could not be served directly as
>> HTML (i.e. either as text/html or encoded in a string inside a JSON
>> response)?
>
>
> We may move that direction, but from what I've seen of form frameworks,
> everyone does things a little differently. As much as I'd like to believe
> there is a single semantic way for how form labels and controls should be
> organized, everyone seems to do things in their own way with their own
> classes and ids. If we provide the whole form layout as is, they may not
> have the flexibility they need.
>
> Our current ecommerce system injects form controls by replacing ^^cart^^ and
> ^^checkout^^ as an example. We tried to follow the CSS Zen Garden approach
> and let people style as needed. For the most part that works, but we still
> ran into situations where people needed something different (which is why
> our last release now supports Twig). With HTML5 and mobile forms, I'm not
> sure locking them into a specific HTML payload will provide the flexibility
> some of our users want.

why wouldn't twig allieviate this for html5/mobile forms in the same way?

>
> As I said, though, we're definitely exploring it.
>
> As as I just learned in #rest, apparently there's a large debate as to
> whether forms are a good or bad thing, so hopefully we didn't just open
> another can. :) I'll do some more research on that before we make a
> decision.

Well my personal opinion is that the level of dynamism forms
facilitate is way overblown relative to the sophistication of API
client code. I think your observation that some will not want to dela
with that dynamism is spot on, but has the unfortunate side effect of
writing off forms as a way to improve the evolvability of your API.
I'm not sure that forms improve developer discovery significantly vs
link relation documentation, and I am very much against adding
complexity to an API interface unless absolutely necessary as it just
presents yet-another-thing-you-have-to-be-concerned-about-causing-client-breakage.

That is completely off the top of my head, I should probably write
something up properly some time - hopefully it is coherent enough to
be understandable.

Cheers
M

Luke Stokes

unread,
Sep 25, 2012, 12:56:58 PM9/25/12
to api-...@googlegroups.com
On Tue, Sep 25, 2012 at 11:32 AM, Mike Kelly <mikeke...@gmail.com> wrote:
On Tue, Sep 25, 2012 at 5:01 PM, Luke Stokes <luke....@gmail.com> wrote:
> On Tuesday, September 25, 2012 10:47:52 AM UTC-5, Mike Kelly wrote:
>>
>> Hi Luke,
>>
>> On Tue, Sep 25, 2012 at 2:49 PM, Luke Stokes <luke....@gmail.com> wrote:
>> > We like how Siren provides actions because our problem domain involves
>> > exposing much of our system so hosted content management platforms can
>> > re-create our entire admin within their interface. Lot's of CRUD, input
>> > forms, etc. If we build out those actions correctly, it might save them
>> > some
>> > time and allow them to have forms that change overtime as we add new
>> > features and fields.
>>
>> Thanks for this, it leaves me with a few more questions:
>>
>> Have you discussed this with potential implementors at the other end?
>> Is their front-end going to call out your API for any pages including
>> these forms?
>
>
> We've discussed it briefly, yes. The initial feedback has been very
> positive. I'm currently thinking about it as a time-saver option for them
> along with a nice way to discover new functionality at run time. They can
> build out their own forms or they can dynamically pull the core pieces from
> us.

Ok so if your consumers short circuit your forms then you won't be
gaining any evolvability benefits, since your API will always need to
support the lowest common denominator that is non-form-aware, right?


Yes, which makes a lot of sense as to why HAL doesn't (yet) include forms. Linking to them (for those that want them) makes sense. I actually started down this route with our API by providing resources which would be used by forms (examples here: curl -k -i -H "X-APi-VERSION: 1" https://api-sandbox.foxycart.com/resources)
 
Are you concerned you that you may be cluttering up your API responses
with these form controls and making them more difficult to read? It is
possible for a formless media type to be time-saving through browsers
that present documentation in-line (the hal browser does this) - you
coud actually have a dummy form in the rel documentation where devs
could input test data.


Good point. I wonder what Kevin of Siren's thoughts on this are? Someone care to start another thread or has this issue been debated at length already? (if so, please send me some links)
 
> Taking this to another level, my business partner is interested in
> letting them customize the forms as full Twig templates. That raises some
> additional concerns to me, but it's something we're exploring. Which leads
> to your next question:

To clarify; these twig templates are for use in a hosted version of
your web app, not relating to the API per se?


They would be used by third party hosted CMS's (as an example) that need to add our admin functionality to their admin via our API. So think of all the features listed at admin.foxycart.com but available on their system.

 
>>
>> Is there a reason that these forms could not be served directly as
>> HTML (i.e. either as text/html or encoded in a string inside a JSON
>> response)?
>
>
> We may move that direction, but from what I've seen of form frameworks,
> everyone does things a little differently. As much as I'd like to believe
> there is a single semantic way for how form labels and controls should be
> organized, everyone seems to do things in their own way with their own
> classes and ids. If we provide the whole form layout as is, they may not
> have the flexibility they need.
>
> Our current ecommerce system injects form controls by replacing ^^cart^^ and
> ^^checkout^^ as an example. We tried to follow the CSS Zen Garden approach
> and let people style as needed. For the most part that works, but we still
> ran into situations where people needed something different (which is why
> our last release now supports Twig). With HTML5 and mobile forms, I'm not
> sure locking them into a specific HTML payload will provide the flexibility
> some of our users want.

why wouldn't twig allieviate this for html5/mobile forms in the same way?

Yes, it would, Sorry if I wasn't clear. Just providing the html forms without a way to customize it would be a limitation.
 

>
> As I said, though, we're definitely exploring it.
>
> As as I just learned in #rest, apparently there's a large debate as to
> whether forms are a good or bad thing, so hopefully we didn't just open
> another can. :) I'll do some more research on that before we make a
> decision.

Well my personal opinion is that the level of dynamism forms
facilitate is way overblown relative to the sophistication of API
client code. I think your observation that some will not want to dela
with that dynamism is spot on, but has the unfortunate side effect of
writing off forms as a way to improve the evolvability of your API.
I'm not sure that forms improve developer discovery significantly vs
link relation documentation, and I am very much against adding
complexity to an API interface unless absolutely necessary as it just
presents yet-another-thing-you-have-to-be-concerned-about-causing-client-breakage.

That is completely off the top of my head, I should probably write
something up properly some time - hopefully it is coherent enough to
be understandable.


It's a great start, for sure. I'd love to see you, Mike and Kevin do a panel discussion on this stuff. :)
 
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.


Pat Cappelaere

unread,
Sep 25, 2012, 1:07:29 PM9/25/12
to api-...@googlegroups.com
Mike,

Action/Activity links require much more information than a link itself.
I think that Siren is doing it right by promoting those as first class citizens and allow me to add other necessary attributes (but it is my own opinion here).
I can also use the same type (class name) as defined in OPG (and same with entities).

JSON-Schema is critical for discovery, validation and documentation of the API. You may not need it but it is vital for many of us (I tried to explain this at REST FEST). Sorry you could not make it.

Pat.

Mike Kelly

unread,
Sep 25, 2012, 1:28:37 PM9/25/12
to api-...@googlegroups.com
Hi Pat,

On Tue, Sep 25, 2012 at 6:07 PM, Pat Cappelaere <cappe...@gmail.com> wrote:
> Mike,
>
> Action/Activity links require much more information than a link itself.

Do you have an example of what you mean here?

> I think that Siren is doing it right by promoting those as first class citizens and allow me to add other necessary attributes (but it is my own opinion here).

you should be ok to add your own additional properties to link objects
in hal+json

Cheers,
M

Pat Cappelaere

unread,
Sep 25, 2012, 2:35:45 PM9/25/12
to api-...@googlegroups.com
Hey Mike,

Here is a sample:
https://gist.github.com/3783607

I would also need to add security access realms on per action basis, also define some constraints (cost, duration…)
Pat.
Reply all
Reply to author
Forward
0 new messages