hypertext json

[Gregg Caines]

Hey all...

I just joined the list hoping to find some people that might be able to poke some holes in some crazy ideas I've had.

I'm aware of a bunch of new Hypertext flavoured JSON types (HAL, Collection+JSON, etc), but I wanted to throw in a new proposal that meets some similar, but slightly different requirements, if anyone's interested in giving some feedback.  If there's something else that does this already, I'm interested in hearing about that as well.

With JSON being the most popular format for APIs (in my experience anyway), having a general purpose hypermedia format for it is pretty important if we're ever going to see a proliferation of hypermedia APIs.  I'm thinking about 3 core requirements:

- Just create a way to add links and forms: Other types could be built on top of this if we can just get link and form capabilities.
- Free-form and general-purpose like XHTML:  Don't target specific document types like "collections", or "CRUD resource", but rather any kind of json document / object.  More specific document types could be built from this though.  Allow links and forms to be added to any object.
- JSON simplicity and style:  Learn from XHTML, but don't blindly mimic it when something can be achieved more simply.  Be mercilessly simple, or the average JSON-aficiondo will not be willing to use the format.
 
Forms are one of the big missing pieces in hypermedia json formats that I've seen, and my initial thoughts were to just use JSON schema documents for them.  There is already great tooling to support JSON schema, including validators and HTML form generators, and JSON doesn't need the UI descriptors that HTML has.

Anyway... I've named the first draft of my idea "Hyper+JSON" and detailed it at http://caines.ca/blog/programming/hyperjson-a-first-draft/ .  If anyone's interested in giving me feedback/pointers/criticism, I'm all ears.

Thanks!
Gregg

[Mike Kelly]

On Mon, Oct 15, 2012 at 5:23 AM, Gregg Caines <cai...@gmail.com> wrote:
> Forms are one of the big missing pieces in hypermedia json formats that I've
> seen

Why do you think that's a "big" missing piece?

fwiw, forms were intentionally left out of HAL but have been sketching
an additional media type extending it with them. let me know if you're
interested in contributing to that.

Cheers,
M

[Gregg Caines]

Well forms are typically the way that the writable side of hypermedia
APIs are described. I haven't really seen another way, other than
out-of-band documentation. JSON is generally unconcerned with UI, so
UI aspects of forms aren't necessary, but the 'name', 'method',
'action', 'content-type', and "form" of the data to be sent for any
non-read request need to be specified somehow, right? The Jon Moore
video at http://vimeo.com/20781278 shows how he's using XHTML forms in
hypermedia apis, and frankly I think it makes unmodified JSON look
like an impossible choice for hypermedia APIs.

I'm proposing that a JSON schema object wrapped in a "form" object
with 'method' and 'href' properties is probably all that's necessary
for JSON. Check out the "_forms object" example at
http://caines.ca/blog/programming/hyperjson-a-first-draft/ for an
example.

HAL looks great by the way. I think I've basically copied your _links
spec verbatim, and done something similar with "_forms". I'm just
trying to keep this as simple as possible, so I haven't tried to
address some of the problems that HAL does, like an equivalent XML
representation, or other features like your _embedded property. I'm
pretty sure I'm going to have a hard enough time selling even just the
idea of links and forms to the JSON api developers I know. They're
pretty merciless about minimalism.

Anyway... I'd be interested to hear what you think about forms in
general. I'd be interested to see other "form" ideas you've been
working on as well.

G

> --
> You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
> To post to this group, send email to hyperme...@googlegroups.com.
> To unsubscribe from this group, send email to hypermedia-we...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/hypermedia-web?hl=en.
>

[Glenn Block]

Correct me if I am wrong, but in HAL you could still have a form, it's just not part of the standard HAL schema. Isn't that correct Mike?

[Mike Kelly]

yeah there's nothing preventing you doing that.

also, the json variant has a media type specification that is entirely
separate from the xml one.

Cheers,
M

Mike

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

[Gregg Caines]

I'd definitely love to help shape forms in HAL if that's in the plan.

At the same time I think I'm looking for something *less* than HAL
(though maybe a base format HAL could use, since it's got a pretty
nice link structure). Formal namespaces, the _embedded property, and
JSON curies are just not necessary for my particular goals though, so
I know you've got different requirements other than just my simple
"let's add links and forms to json".

I'm guessing people are going to say "just don't use those features",
which is entirely a possibility, but when I write libraries that don't
include those features, I certainly can't say it's HAL. I don't know
how to explain myself better than to say "less features" is the main
feature I'm looking for. I'm going to have a hard enough time just
selling the idea of links to the developers I work with.

This isn't a criticism of HAL at all by the way, so I hope it doesn't
come across like that... I just have a different set of requirements.
There are already a bunch of hypermedia formats already that have
differing fits in different scenarios (xhtml, atompub, html, rss,
gdata, odata, etc).

G

[Mike Kelly]

On Mon, Oct 15, 2012 at 10:23 PM, Gregg Caines <gr...@caines.ca> wrote:
> I'd definitely love to help shape forms in HAL if that's in the plan.
>
> At the same time I think I'm looking for something *less* than HAL
> (though maybe a base format HAL could use, since it's got a pretty
> nice link structure). Formal namespaces, the _embedded property, and
> JSON curies are just not necessary for my particular goals though

Hi Gregg thanks for sharing your thoughts..

first off - yes I would definitely like you to help shape hal forms. I
forgot to share the link earlier but here is the latest incarnation of
"halo": https://gist.github.com/3808215

to your other points:

What do you mean by formal namespaces?

JSON curies are an optional feature. They're used to keep the property
names in the links object when the rels are URIs. It's relatively
simple and useful in practice, do you have an alternative approach?

Embedding resources is a more common use case right now than forms or
even links. It makes sense to standardise how this is achieved. Do you
have an alternative approach for this too?

Cheers,
M

[Mike Kelly]

On Mon, Oct 15, 2012 at 11:14 PM, Mike Kelly <mikeke...@gmail.com> wrote:
> JSON curies are an optional feature. They're used to keep the property
> names in the links object when the rels are URIs. It's relatively
> simple and useful in practice, do you have an alternative approach?

woops, the second sentence in the above was meant to say:

They're used to keep the length of the property names down in the

links object when the rels are URIs.

Cheers,
M

[Steve Klabnik]

If you don't use an <UL> tag, is it not HTML?

[Gregg Caines]

Ha well you're framing this like we have the same requirements. I'm
not really sure we do, but I'll bite, because I'd love to hear more
about HAL either way. I liked your forms draft and I commented on it
with some pretty minor feedback. I'm really surprised at how close it
is to what I was thinking about.

> What do you mean by formal namespaces?

Like in this example:
https://github.com/HalBuilder/halbuilder-test-resources/blob/develop/src/main/resources/exampleWithSubresource.json
. I'm assuming the 'ns:' prefix is for namespacing. Let me know if
I'm wrong, or if it doesn't have any HAL-specific meaning. They're
just characters in base JSON though.

> JSON curies are an optional feature. They're used to keep the property
> names in the links object when the rels are URIs. It's relatively
> simple and useful in practice, do you have an alternative approach?

Alright... this isn't a huge deal really. I can see the utility. I'm
just extremely complexity-averse in case you haven't noticed. ;)

> Embedding resources is a more common use case right now than forms or
> even links. It makes sense to standardise how this is achieved. Do you
> have an alternative approach for this too?

This one is definitely the weirdest aspect to me. JSON already lets
you embed objects inherently. Any property of an object can be an
object itself. What extra semantic does _embedded add? This lead me
to assume more than anything that you must have some requirement that
I don't have.

G

[Mike Kelly]

On Tue, Oct 16, 2012 at 12:48 AM, Gregg Caines <gr...@caines.ca> wrote:
> Ha well you're framing this like we have the same requirements. I'm
> not really sure we do, but I'll bite, because I'd love to hear more
> about HAL either way.

We do have the same requirements, the whole point of HAL was to be
'simple'. This is why it didn't include forms. It's actually a bit
confusing that you are picking up on relatively simple parts of HAL
and claiming they make the type 'too complicated', and yet at the same
time you are apparently looking to add something form-like and add a
dependency to JSON schema.

> I liked your forms draft and I commented on it
> with some pretty minor feedback. I'm really surprised at how close it
> is to what I was thinking about.

Yeah it's been knocking around for about a year, here's some older examples:

https://gist.github.com/893552/6faa6a8ac24f78a2b186a37a1d9b26c54d3579b2

>> What do you mean by formal namespaces?
>
> Like in this example:
> https://github.com/HalBuilder/halbuilder-test-resources/blob/develop/src/main/resources/exampleWithSubresource.json
> . I'm assuming the 'ns:' prefix is for namespacing. Let me know if
> I'm wrong, or if it doesn't have any HAL-specific meaning. They're
> just characters in base JSON though.

Those are curies

>> JSON curies are an optional feature. They're used to keep the property
>> names in the links object when the rels are URIs. It's relatively
>> simple and useful in practice, do you have an alternative approach?
>
> Alright... this isn't a huge deal really. I can see the utility. I'm
> just extremely complexity-averse in case you haven't noticed. ;)

As above, then i'm not sure why you are interested in form-like controls.

>> Embedding resources is a more common use case right now than forms or
>> even links. It makes sense to standardise how this is achieved. Do you
>> have an alternative approach for this too?
>
> This one is definitely the weirdest aspect to me. JSON already lets
> you embed objects inherently. Any property of an object can be an
> object itself. What extra semantic does _embedded add? This lead me
> to assume more than anything that you must have some requirement that
> I don't have.

There's a couple of reasons:

1. embedded resources are isolated and therefore distinguishable from
'normal' properties.
2. embedded resources are associated via link relations, embedding
something is like linking to it but including it inline as an
efficiency measure.

embedded is only for embedding other resources not for any
property-thats-and-object. e.g:

GET /hover-donkey

{
_links: { self: { href: "/hover-donkey" } },
legs: {
front-left: { length: 14 },
front-right: { length: 12 }
}
_embedded: {
owner: {
_links: { self: { href: "/bob" } },
name: "Bob"
}
}
}

above, legs aren't resources in their own right (i.e. they dont have a
URI) so they dont need to be inside embedded.

Cheers,
M

[Gregg Caines]

Alright... I'm probably the confused one...  

If JSON-HAL is aimed at my requirements, how do you create APIs with json-hal that aren't read-only?  Do you keep out-of-band docs elsewhere to describe how to write?  Or do you only write read-only APIs?  Or is there some part of the hal docs that I've missed that describes a protocol for methods other than GET?  Forms solve the same problem that links do (discoverability, evolvability, etc), but for the writable-side of the API.  I'm all for maximum simplicity, but it's got to be within the context of actually solving the problem.  If you have a way of achieving discoverable writability without forms, I've definitely missed it.  Throw me a clue.  :)

I'd be interested to know how anyone else is solving these issues in writable hypermedia JSON apis as well, especially if they're not using something like forms.

G

[Dietrich Schulten]

To me it seems that html forms could be used in an otherwise json based api. Based on Jon Moore's ideas I have started a demo client which submits html forms and follows rels in json responses https://github.com/dschulten/spring-hateoas-rest-service-sample. Who says an api must be all json? A client can request a preferred format (json) and the server can respond with something else (html), possibly of course something standardized.
I see the need for a client framework which supports a good set of standard media types and is easily extensible to support custom types. The project above explores this possibility, maybe you can grab some ideas there :-)
Best regards,
Dietrich

[Glenn Block]

A form is just a concept. You don't "need" to use HTML to submit a form, though you certainly can. There's nothing wrong with however (imo) introducing a form notion into JSON / having a JSON API return forms.

[Mike Kelly]

On Tue, Oct 16, 2012 at 3:38 AM, Gregg Caines <gr...@caines.ca> wrote:
> Alright... I'm probably the confused one...
>
> If JSON-HAL is aimed at my requirements, how do you create APIs with
> json-hal that aren't read-only? Do you keep out-of-band docs elsewhere to
> describe how to write? Or do you only write read-only APIs? Or is there
> some part of the hal docs that I've missed that describes a protocol for
> methods other than GET? Forms solve the same problem that links do
> (discoverability, evolvability, etc), but for the writable-side of the API.
> I'm all for maximum simplicity, but it's got to be within the context of
> actually solving the problem. If you have a way of achieving discoverable
> writability without forms, I've definitely missed it. Throw me a clue. :)
>
> I'd be interested to know how anyone else is solving these issues in
> writable hypermedia JSON apis as well, especially if they're not using
> something like forms.

Forms aren't a requirement for a hypermedia APIs, they are an optional
affordance. Whether or not you include them in your API comes down to
your objectives and context. If you are concerned about keeping
complexity down I would urge you to avoid forms in your API.

You can drive write interactions via link relations..

If your API is driven by link relations, those link relations are
URIs, and the documentation for each link relations is exposed at
their URI - then the information is not out-of-band. I put up an
example API here:

http://haltalk.herokuapp.com

Cheers,
M

[Dietrich Schulten]

@glenn, no, nothing is wrong with a json form notation. Siren is trying that, too. It is just that html forms are well defined.

[Glenn Block]

Agreed that HTML forms are well defined are recognized universally which is a very strong argument of Jon's. It's a bit of a chicken and egg problem. Yes HTML is ubiquitous, but if we can agree on a standard format the same "could" happen over time. There's a lot of JSON clients out there after all.

[Gregg Caines]

I'd actually consider what you've done there out-of-band, because
there's nothing an intelligent json client can do to interpret your
html documentation about the relationship (eg
http://haltalk.herokuapp.com/rels/users ).

If the rels docs were written in json instead, you get quite a lot
more. For instance, if you want to change the HTTP method and URI for
writing, you can do that and an intelligent client can just pick that
up automatically (with no changes by a human). Also if your body
fields change there is some opportunity for evolvability without
changing the client as well. Dropping a field can be picked up by an
intelligent client easily. Adding new fields can be picked up
automatically by an agent that passes the requirements on to a human
end-user. If you'd done it in json instead (or even just some
semantic markup), then what those rels point to is what I would
consider to be a form. I can use a different word if that's confusing
though. I just mean something that specifies uri, method, and body
requirements of different non-GET requests. I'm not talking about
copying html forms verbatim.

XHTML forms achieve this. Jon Moore's demo shows it pretty well, and
it blows my mind. I just don't see these types of evolvable APIs
catching on with the average developer unless they can do it in json.

G

[Mike Kelly]

On Tue, Oct 16, 2012 at 6:08 PM, Gregg Caines <gr...@caines.ca> wrote:
> I'd actually consider what you've done there out-of-band, because
> there's nothing an intelligent json client can do to interpret your
> html documentation about the relationship (eg
> http://haltalk.herokuapp.com/rels/users ).

It's not out of band.. the links are in the responses and they are
driving the client forward. It iss less dynamic, but it's not out of
band.

A truly intelligent client could read, interpret and apply the natural
language in the html doc. That line of argument will just go round in
circles.

> If the rels docs were written in json instead, you get quite a lot
> more. For instance, if you want to change the HTTP method and URI for
> writing, you can do that and an intelligent client can just pick that
> up automatically (with no changes by a human).

Bear in mind this is not a question of whether m2m forms work in
theory, they do. It's a question of whether they are workable in
practice and/or whether they are worth the additional complexity.

URI changes are possible with links, and how often do you arbitrarily
switch from one HTTP method to another? Is automated code really going
to deal with shifting between safe/non-safe or
idempotent/non-idempotent requests?

> Also if your body
> fields change there is some opportunity for evolvability without
> changing the client as well. Dropping a field can be picked up by an
> intelligent client easily. Adding new fields can be picked up
> automatically by an agent that passes the requirements on to a human
> end-user.

If that was the primary use-case, why not use HTML for this? It is the
defacto media type for representing GUI hypertext interfaces. The vast
majority know what HTML is and how it is used for GUI apps.

> If you'd done it in json instead (or even just some
> semantic markup), then what those rels point to is what I would
> consider to be a form. I can use a different word if that's confusing
> though. I just mean something that specifies uri, method, and body
> requirements of different non-GET requests. I'm not talking about
> copying html forms verbatim.

Again, it depends on the use-case.

If you are talking about 'smart clients' that represent dynamic
hypertext interfaces to humans - that is exactly what browsers do and
what HTML is for. There are a lot of very good reasons to just use
HTML and not very many to create and/or use something based on json
that does exactly the same thing.

If you are talking about an API with machine clients interfacing with
it - and you care about keeping your API 'simple' - you should have
some serious reservations about the cost-benefit of dynamic controls.
If we run through some m2m scenarios with outcomes for both forms (f)
and links (l):

1. Remove field
(f) Field removed from request
(l) Request includes now-redundant field but server just ignores it

conclusion: link is less complex than form and achieves same outcome.

2. Add optional field
(f) Field not filled in until client updated
(l) Field not included until client updated

conclusion: link is less complex than form and achieves same outcome.

3. Add required field
(f) Clients, realising they can't complete the form, error before
making the request - leaving server unaware of client failures.
(l) Request made omitting required field. Server aware of client
failure, returns 4xx - client aware.

conclusion: link is less complex and arguably preferable outcome
because server has visibility into how clients are dealing with the
change.

Imo, the above demonstrates why it should not be question of "do m2m
forms work?" but actually "are they worth it?".

Cheers,
M

[mca]

MK:

while I completely agree that the issue on "form-style" designes for m2m rests primarily on whether the added work is "worthwhile", i wanted to take a moment to bring up a few additional points on your M2M cases taht have come up in the last year while i work on this problem myself.

<snip>

2. Add optional field
(f) Field not filled in until client updated
(l) Field not included until client updated

conclusion: link is less complex than form and achieves same outcome.

</snip>

this is only one possible case for "adding an optional field." the more common case that i work with is _moving_ an existing field (i.e. the m2m client already *knows* this field, it just appears in a new location/response) and the _appearance_ of a "known" field that has not yet shown up in any previous responses (i.e. the client was built to recognize and handle fieldZ but the initial server releases didn't include fieldZ until later in the lifetime of the system).

in these two cases a "form-style" design allows a client to adapt to the runtime modifications within responses w/o the need for human intervention and this can add some positive benefit for systems that frequently change or need to exist over a long period of time.

<snip> 

3. Add required field
(f) Clients, realising they can't complete the form, error before
making the request - leaving server unaware of client failures.
(l) Request made omitting required field. Server aware of client
failure, returns 4xx - client aware.

conclusion: link is less complex and arguably preferable outcome
because server has visibility into how clients are dealing with the
change.

</snip>

it is possible that creating new MUST elements in a design over the lifetime of the system will require some type of intervention. however, this is not always the case. for example changing a SHOULD or MAY into a MUST (i.e. the client already "knows" this element) can be successfully handled by a "forms-style" client.

SOME CASES NOT OUTLINED IN YOUR REPLY

it is also possible to arrange interactions such that rel/action names can be a non-issue for m2m clients, but only in cases where the actions presented in the response are assumed to all be executed by the client and/or there is only one action to execute. in this case, the client is only interested in the protocol-level details (safety, idempotence) and not the semantic meaning of the action (i.e. no "choice" is required by the m2m client).

ITS THE ONTOLOGY, NOT THE AFFORDANCE

in my experience to-date on this topic, the key "breaking point" for m2m cases is not the use of "form-style" hypermedia, but the modification of the data points (ontology, dictionary, vocabulary, etc.) known to the m2m client when it was "built". introducing new members of the vocabulary (either data names or rel/action names) will almost always require intervention. 

i must admit this last point (on ontology) bothers me greatly<g>. it seems to be leading me into a very dark and scary forest the likes of which i am loathe to enter. but that's another story...

Cheers!

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

Cheers,
M

[Mike Kelly]

On Tue, Oct 16, 2012 at 7:46 PM, mca <m...@amundsen.com> wrote:
> MK:
>
> while I completely agree that the issue on "form-style" designes for m2m
> rests primarily on whether the added work is "worthwhile", i wanted to take
> a moment to bring up a few additional points on your M2M cases taht have
> come up in the last year while i work on this problem myself.
>
> <snip>
> 2. Add optional field
> (f) Field not filled in until client updated
> (l) Field not included until client updated
>
> conclusion: link is less complex than form and achieves same outcome.
> </snip>
>
> this is only one possible case for "adding an optional field." the more
> common case that i work with is _moving_ an existing field (i.e. the m2m
> client already *knows* this field, it just appears in a new
> location/response) and the _appearance_ of a "known" field that has not yet
> shown up in any previous responses (i.e. the client was built to recognize
> and handle fieldZ but the initial server releases didn't include fieldZ
> until later in the lifetime of the system).
>
> in these two cases a "form-style" design allows a client to adapt to the
> runtime modifications within responses w/o the need for human intervention
> and this can add some positive benefit for systems that frequently change or
> need to exist over a long period of time.

Right, but the longevity is relative to the complexity of the form..
most form designs are not capable much more than trivial renaming of
k/v pairs, which I doubt would afford enough control to last a 'long
period of time'.

> <snip>
>
> 3. Add required field
> (f) Clients, realising they can't complete the form, error before
> making the request - leaving server unaware of client failures.
> (l) Request made omitting required field. Server aware of client
> failure, returns 4xx - client aware.
>
> conclusion: link is less complex and arguably preferable outcome
> because server has visibility into how clients are dealing with the
> change.
> </snip>
>
> it is possible that creating new MUST elements in a design over the lifetime
> of the system will require some type of intervention. however, this is not
> always the case. for example changing a SHOULD or MAY into a MUST (i.e. the
> client already "knows" this element) can be successfully handled by a
> "forms-style" client.

Ok but what kind of scenarios do forms cover here that are unafforded by links?

My underlying point here is if the outcome is equivalent then why
bother with the ceremony of forms? Why make your clients life harder
than it has to be?

> SOME CASES NOT OUTLINED IN YOUR REPLY
> it is also possible to arrange interactions such that rel/action names can
> be a non-issue for m2m clients, but only in cases where the actions
> presented in the response are assumed to all be executed by the client
> and/or there is only one action to execute. in this case, the client is only
> interested in the protocol-level details (safety, idempotence) and not the
> semantic meaning of the action (i.e. no "choice" is required by the m2m
> client).

So the client is basically a completely stateless dumb worker? I don't
know much about that, but it's not a requirement for me right now so
difficult to comment.

> ITS THE ONTOLOGY, NOT THE AFFORDANCE
> in my experience to-date on this topic, the key "breaking point" for m2m
> cases is not the use of "form-style" hypermedia, but the modification of the
> data points (ontology, dictionary, vocabulary, etc.) known to the m2m client
> when it was "built". introducing new members of the vocabulary (either data
> names or rel/action names) will almost always require intervention.
>
> i must admit this last point (on ontology) bothers me greatly<g>. it seems
> to be leading me into a very dark and scary forest the likes of which i am
> loathe to enter. but that's another story...

agreed :)

btw, you should drop in irc more

Cheers,
M

[mca]

<snip>

> in these two cases a "form-style" design allows a client to adapt to the
> runtime modifications within responses w/o the need for human intervention
> and this can add some positive benefit for systems that frequently change or
> need to exist over a long period of time.

Right, but the longevity is relative to the complexity of the form..
most form designs are not capable much more than trivial renaming of
k/v pairs, which I doubt would afford enough control to last a 'long
period of time'.

</snip>

do we've gotten beyond the point of recognizing what i describes is possible (since i am actively doing it) and you are saying you don't think it's worth it, right?

<snip>

Ok but what kind of scenarios do forms cover here that are unafforded by links?

</snip>

I don't understand the Q

<snip>

My underlying point here is if the outcome is equivalent then why
bother with the ceremony of forms? Why make your clients life harder
than it has to be?

</snip>

you stated:

> 3. Add required field
> (f) Clients, realising they can't complete the form...

and i offered cases where the "add required field" scenario does not result in "they can't complete the form..." that's not "...outcome is equivalent."

<snip>

So the client is basically a completely stateless dumb worker?

</snip>

no, the client is a stateless worker or, if you prefer the judgmental words: the client is *superiorly* a *successully* stateless *smart* worker<g>.

<snip>

btw, you should drop in irc more

</snip>

yep, i should!

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

Cheers,
M

[Mike Kelly]

On Tue, Oct 16, 2012 at 8:20 PM, mca <m...@amundsen.com> wrote:
> <snip>
>> in these two cases a "form-style" design allows a client to adapt to the
>> runtime modifications within responses w/o the need for human intervention
>> and this can add some positive benefit for systems that frequently change
>> or
>> need to exist over a long period of time.
>
> Right, but the longevity is relative to the complexity of the form..
> most form designs are not capable much more than trivial renaming of
> k/v pairs, which I doubt would afford enough control to last a 'long
> period of time'.
> </snip>
>
> do we've gotten beyond the point of recognizing what i describes is possible
> (since i am actively doing it) and you are saying you don't think it's worth
> it, right?

Yes. In your deployment(s), how many different client implementations
do you have against those forms? Are you able to share the form
design?

> <snip>
> Ok but what kind of scenarios do forms cover here that are unafforded by
> links?
> </snip>
> I don't understand the Q

What set of SHOULD/MAY-to-MUST changes could a client survive if the
control was a form that it could not if the control was a link?

> <snip>
>
> My underlying point here is if the outcome is equivalent then why
> bother with the ceremony of forms? Why make your clients life harder
> than it has to be?
> </snip>
>
> you stated:
>> 3. Add required field
>> (f) Clients, realising they can't complete the form...
> and i offered cases where the "add required field" scenario does not result
> in "they can't complete the form..." that's not "...outcome is equivalent."

So, in a scenario where a field was required that the client was not
currently designed to supply - if the form-driven client came across
this form it would omit the field marked required and make the request
regardless? I have a couple of problems with that:

1. your clients are now undermining the required control to the point
where it is redundant at run time
2. this would result in exactly the same request as the link-driven
approach (i.e. request issued that omits a required field and results
in a 4xx)

Afaict, that actually make the form control even less useful.

Cheers,
M

[Glenn Block]

I am personally a BIG fan of using forms in particular because of their self-documenting nature. For example a form can actually inform me that an element within the form is optional or required where the client can then do some validation. A form can even include metadata describing ranges, formats etc. Yes you can go crazy with it / abuse it. For the client it's very easy though to iterate through that metdata and take some action as result, like informing the UI critical values are missing. That information is also contextual to the user as the form is an instance level thing as opposed to being static schema. Beyond that forms can offer other things like support for sending other types of data like documents, which there's no easy way to do via a link.

[mca]

inline this time...

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

On Tue, Oct 16, 2012 at 3:35 PM, Mike Kelly <mikeke...@gmail.com> wrote:

On Tue, Oct 16, 2012 at 8:20 PM, mca <m...@amundsen.com> wrote:
> <snip>
>> in these two cases a "form-style" design allows a client to adapt to the
>> runtime modifications within responses w/o the need for human intervention
>> and this can add some positive benefit for systems that frequently change
>> or
>> need to exist over a long period of time.
>
> Right, but the longevity is relative to the complexity of the form..
> most form designs are not capable much more than trivial renaming of
> k/v pairs, which I doubt would afford enough control to last a 'long
> period of time'.
> </snip>
>
> do we've gotten beyond the point of recognizing what i describes is possible
> (since i am actively doing it) and you are saying you don't think it's worth
> it, right?

Yes. In your deployment(s), how many different client implementations
do you have against those forms? Are you able to share the form
design?

**********************

diff client impls against the same server impl? not sure; more than one independent impl, i know of.

the design is nothing unusual, AFAIK:

href

rel

input-collection where each input includes

- name

- value

- regex (this is where MUST/MAY information is communicated)

*********************** 

 

> <snip>
> Ok but what kind of scenarios do forms cover here that are unafforded by
> links?
> </snip>
> I don't understand the Q

What set of SHOULD/MAY-to-MUST changes could a client survive if the
control was a form that it could not if the control was a link?

**********************

in the example above, the MUST/MAY is sent in the representation and read at runtime. does your link implementation (non-form) support this runtime mod of MAY/MUST? if so, how does that work?

**********************

> <snip>
>
> My underlying point here is if the outcome is equivalent then why
> bother with the ceremony of forms? Why make your clients life harder
> than it has to be?
> </snip>
>
> you stated:
>> 3. Add required field
>> (f) Clients, realising they can't complete the form...
> and i offered cases where the "add required field" scenario does not result
> in "they can't complete the form..." that's not "...outcome is equivalent."

So, in a scenario where a field was required that the client was not
currently designed to supply - if the form-driven client came across
this form it would omit the field marked required and make the request
regardless? I have a couple of problems with that:

1. your clients are now undermining the required control to the point
where it is redundant at run time
2. this would result in exactly the same request as the link-driven
approach (i.e. request issued that omits a required field and results
in a 4xx)

Afaict, that actually make the form control even less useful.

***********

yeah, this is old dirt we're chewing here. anything where "the client was not design to supply" will require intervention and i agreed to that at the start of this convo. 

however, i offered cases (ones that i did not see in your list) where "the client *was* designed to supply" the information. specifically, i detailed two cases where i've found this to be true (moving and sudden appearance of predefined data point). i also outlined at least one case where the rel/action information (not a data point) can be made superflous through a change in message design.

finally, note that i am not offering these as examples of how a link-style design *fails* to handle these problems. i am offering these examples as cases where "form-style" design works based on cases i have experienced.

************ 

[Mike Kelly]

On Tue, Oct 16, 2012 at 8:53 PM, mca <m...@amundsen.com> wrote:
> On Tue, Oct 16, 2012 at 3:35 PM, Mike Kelly <mikeke...@gmail.com> wrote:
>> What set of SHOULD/MAY-to-MUST changes could a client survive if the
>> control was a form that it could not if the control was a link?
>
> **********************
> in the example above, the MUST/MAY is sent in the representation and read at
> runtime. does your link implementation (non-form) support this runtime mod
> of MAY/MUST? if so, how does that work?
> **********************

No. I would just define it as a SHOULD in the first place. That way
the client will include the field in the request whenever possible. Do
you have a practical example of a scenario you can cover with this
dynamic runtime MAY-to-MUST, which would not be solved with a SHOULD?

> finally, note that i am not offering these as examples of how a link-style
> design *fails* to handle these problems. i am offering these examples as
> cases where "form-style" design works based on cases i have experienced.

That being the case, why bother with forms? They're more complicated
and they don't gain you any more evolvability (hence why your examples
don't show link-style failing).

Cheers,
M

[mca]

again inline...

On Tue, Oct 16, 2012 at 4:17 PM, Mike Kelly <mikeke...@gmail.com> wrote:

On Tue, Oct 16, 2012 at 8:53 PM, mca <m...@amundsen.com> wrote:
> On Tue, Oct 16, 2012 at 3:35 PM, Mike Kelly <mikeke...@gmail.com> wrote:

>> What set of SHOULD/MAY-to-MUST changes could a client survive if the
>> control was a form that it could not if the control was a link?
>
> **********************
> in the example above, the MUST/MAY is sent in the representation and read at
> runtime. does your link implementation (non-form) support this runtime mod
> of MAY/MUST? if so, how does that work?
> **********************

No. I would just define it as a SHOULD in the first place. That way
the client will include the field in the request whenever possible. Do
you have a practical example of a scenario you can cover with this
dynamic runtime MAY-to-MUST, which would not be solved with a SHOULD?

*********
the working cases i have in mind are a multi-tenancy system where each "customer" can make varying MUST/MAY configurations and have this information sent w/ representations at runtime. A single client app, aware of the "complete" set of data elements responds to representations that contain varying state transition instructions as they appear at runtime.

********** 

> finally, note that i am not offering these as examples of how a link-style
> design *fails* to handle these problems. i am offering these examples as
> cases where "form-style" design works based on cases i have experienced.

That being the case, why bother with forms? They're more complicated
and they don't gain you any more evolvability (hence why your examples
don't show link-style failing).

*********

and here is where you and i always arrive. 

now, are we in agreement that both approaches are capable of solving the problems at hand? do we agree this is not a matter of what is possible, but instead what is preferable? that this is a choice of *design*, not capability?

[Glenn Block]

I bother because of their self-documenting nature. That to me is one of the biggest advantages.

Cheers,
M

[Mike Kelly]

On Tue, Oct 16, 2012 at 9:26 PM, Glenn Block <glenn...@gmail.com> wrote:
> I bother because of their self-documenting nature. That to me is one of the
> biggest advantages.

Do you mean self-documenting to developers or coded clients?

Cheers,
M

[Moore, Jonathan (CIM)]

On 10/16/12 4:17 PM, "Mike Kelly" <mikeke...@gmail.com> wrote:

>That being the case, why bother with forms? They're more complicated
>and they don't gain you any more evolvability (hence why your examples
>don't show link-style failing).

FWIW, while forms may be more complicated than links, they're not THAT
complicated. Here's XHTML form submission in under 200 lines of Java (a
language with a reputation for verbosity), a good chunk of which are
imports, whitespace, and comments:

https://raw.github.com/cimlabs/hypermedia-client-java/master/src/main/java/
com/comcast/cim/rest/client/xhtml/RequestBuilder.java

(shortened: http://bit.ly/R9zDSf)

Jon
........
Jon Moore
Comcast Cable

[Mike Kelly]

On Tue, Oct 16, 2012 at 9:35 PM, Moore, Jonathan (CIM)
<Jonatha...@comcast.com> wrote:
> On 10/16/12 4:17 PM, "Mike Kelly" <mikeke...@gmail.com> wrote:
>
>>That being the case, why bother with forms? They're more complicated
>>and they don't gain you any more evolvability (hence why your examples
>>don't show link-style failing).
>
> FWIW, while forms may be more complicated than links, they're not THAT
> complicated. Here's XHTML form submission in under 200 lines of Java (a
> language with a reputation for verbosity), a good chunk of which are
> imports, whitespace, and comments:
>

Dependencies are still complexity, right? It's also a more convoluted
interaction pattern.

Even if it was only very slightly more complex/convoluted (imo, it's
more than that), I'd still be left asking "why bother?".

Cheers,
M

[Moore, Jonathan (CIM)]

On 10/16/12 4:42 PM, "Mike Kelly" <mikeke...@gmail.com> wrote:

>On Tue, Oct 16, 2012 at 9:35 PM, Moore, Jonathan (CIM)
><Jonatha...@comcast.com> wrote:
>> On 10/16/12 4:17 PM, "Mike Kelly" <mikeke...@gmail.com> wrote:
>>
>>>That being the case, why bother with forms? They're more complicated
>>>and they don't gain you any more evolvability (hence why your examples
>>>don't show link-style failing).
>>
>> FWIW, while forms may be more complicated than links, they're not THAT
>> complicated. Here's XHTML form submission in under 200 lines of Java (a
>> language with a reputation for verbosity), a good chunk of which are
>> imports, whitespace, and comments:
>>
>
>Dependencies are still complexity, right? It's also a more convoluted
>interaction pattern.

Sure. But operating systems, browsers, mobile platforms, etc. are all
complex too. Few clients are built without dependencies. The main issue is
how complex it is for the client developer, which with modern
package/dependency management can be "not that hard." The code I linked to
could be used across multiple application domains; it is XHTML-specific,
not application specific. It exposes a pretty simple interface, which is:
"find the form with this particular class, and then submit it with these
key/value pairs" (or rather, it's "give me a built request I can then
issue without examining further).

>Even if it was only very slightly more complex/convoluted (imo, it's
>more than that)

The API signature is: submitForm(String classAttr, Map<String,String>
keyvals)

What exactly do you find complex about this? Is it just that arguments are
passed in? To be clear, I admit it is more complex than just following a
link with a certain rel, which is followLink(String rel).

Jon

>
>I'd still be left asking "why bother?".

For APIs delivered via HTML, it means a (human + browser) combination is
fully capable of operating the API, which has proven operationally useful
for us. As we've discussed previously, this can be achieved via the HAL
browser, although I would then suggest the HAL browser is an additional
dependency on the overall development ecosystem, as you identified the
form library above as a dependency. In addition, HTML forms make an
intuitive API interface possible; filling out text boxes and hitting a
submit button is a lot easier than writing JSON and specifying HTTP
headers, meaning that (non-developer-human + browser) is a capable client
combination. In addition, curl makes it quite easy to fill out forms from
the command line via -d options (as opposed to crafting, say, JSON request
bodies).

[Gregg Caines]

My only quibble is probably more of a marketing one than a technical one.

I just don't believe json can be unseated as the leading API
media-type. I think the only chance hypermedia APIs have of
flourishing is by bringing hypermedia to json (and even then I have to
figure out a better way to explain why we need links and forms,
because I'm apparently terrible at it :) ). Developers are in a huge
hurry to just get something working, and rarely care upfront about
evolvability and self-description. They're currently happy to
hard-code all the possible urls and methods into a weird brittle
client library and move on.

I haven't taken a scientific poll, but I imagine XML (and hence xhtml)
lost the battle because dom parsing and traversal is much more painful
than dealing with the hashs/maps that are returned from JSON.parse().
Even if this could be solved (E4X almost did, I guess), I believe
XML's well has already been poisoned.

Now if json could do what xhtml does as far as describing both read
AND write characteristics, hypermedia APIs might have a fighting
chance at the average developer's mindshare. Otherwise, I think
hypermedia APIs will continue to be considered the stuff of
architecture astronauts and academia.

G


On Tue, Oct 16, 2012 at 2:02 PM, Moore, Jonathan (CIM)

[Mike Kelly]

On 17 Oct 2012, at 06:35, Gregg Caines <gr...@caines.ca> wrote:

> I think
> hypermedia APIs will continue to be considered the stuff of
> architecture astronauts and academia.

The majority will look at forms this way even if you reinvent them in json.

[Gregg Caines]

You're right. I know you're right, because they already say the same
things about links in json. Links are kind of a requirement of
hypermedia though. If we value simplicity over requirements, then we
might as well go with blank text files and call it a day.

We can agree to disagree on forms though. This is just a technical
discussion and I'm not emotionally invested in my proposed solution
(or even my proposed requirements). What might be more interesting is
if we could come to an agreement on how links alone should work first
(without forms or curies or embedded documents or anything else).
Maybe that's a more realistic goal?

G

[Darrel Miller]

Glenn,

If that's what you want to use forms for then why not put the
definition of the form at the other end of the link relation URL.
That metadata that defines which fields are optional or required has a
completely different lifetime to the data it is describing and so IMHO
should be a distinct resource. Inlining form metadata is mixing
concerns and it requires me to re-download that metadata for every
resource. That metadata should be highly cacheable.

Looking at this a different way, the form definition is really just a
declarative way of doing code-on-demand. The form metadata tells the
client how the information should be captured and processed.

I personally like using link relations for specifying this processing
metadata because it forces the separation of concerns. That is until
people start adding a ton of attributes to the link relation element
:-)

Darrel

[Glenn Block]

I am ok with forms as a resource though I think there are pros / cons. On the con side, it does require extra http calls to get the form, however it is "potentially" cachable. I say potentially because a common practice with forms is that they are pre-filled, and if they are secure over HTTPs then the web is not going to help you caching wise.

We can debate on this though. The issue here though is Mike is saying forms themselves are not valuable, and I personally don't subscribe to that.

[Mike Kelly]

On Wed, Oct 17, 2012 at 7:29 PM, Glenn Block <glenn...@gmail.com> wrote:
> I am ok with forms as a resource though I think there are pros / cons. On
> the con side, it does require extra http calls to get the form, however it
> is "potentially" cachable. I say potentially because a common practice with
> forms is that they are pre-filled, and if they are secure over HTTPs then
> the web is not going to help you caching wise.

You can still make use of local client caches and/or gateway caches
behind your SSL endpoint.

>
> We can debate on this though. The issue here though is Mike is saying forms
> themselves are not valuable, and I personally don't subscribe to that.
>

I'm still not clear to who/what forms are supposed to be "more
self-describing", the developer or the coded client?

Cheers,
M

[Glenn Block]

CIL

On Wed, Oct 17, 2012 at 11:58 AM, Mike Kelly <mikeke...@gmail.com> wrote:

On Wed, Oct 17, 2012 at 7:29 PM, Glenn Block <glenn...@gmail.com> wrote:
> I am ok with forms as a resource though I think there are pros / cons. On
> the con side, it does require extra http calls to get the form, however it
> is "potentially" cachable. I say potentially because a common practice with
> forms is that they are pre-filled, and if they are secure over HTTPs then
> the web is not going to help you caching wise.

You can still make use of local client caches and/or gateway caches
behind your SSL endpoint.

GB: Yes you can use local caches, but that is not the same as being able to leverage web proxies and such that exist on the internet 

>
> We can debate on this though. The issue here though is Mike is saying forms
> themselves are not valuable, and I personally don't subscribe to that.
>

I'm still not clear to who/what forms are supposed to be "more
self-describing", the developer or the coded client?

GB: Can be both.

 

Cheers,

M

[Darrel Miller]

I honestly don't think embedded forms add as much value as is
perceived and I don't think they are the best approach.

Let's consider a concrete example,

We start with an existing list of foos.

GET /foos
=>
Content-Type: application/hal+xml

<resource>
<resource rel="http://myapp.com/rels/foo" href="http://myapp.com/foo/23">
<description>A small green foo</description>
</resource>
<resource rel="http://myapp.com/rels/foo" href="http://myapp.com/foo/13">
<description>A unlucky foo</description>
</resource>
<resource rel="http://myapp.com/rels/foo" href="http://myapp.com/foo/42">
<description>An enlightended foo</description>
</resource>
<link rel="http://myapp.com/rels/create-foo" href="http://myapp.com/foos"/>
</resource>

My client detects that there is a link with the rel
"http://myapp.com/rels/create-foo". The client must know either
exactly how to activate this link, or it must know that by doing a GET
on the link rel URI that it will get more instructions. This is
similar to a client retrieving a document and knowing how to process
that media type's notion of a form.

By splitting the form resource from the actual resource representation
itself we get a number of benefits. We don't need to send the form
metadata redundantly. It can be cached. We don't need to create a
form "mechanism" for hal and collection+json and siren and hyper+json,
ad infinitum. The client could negotiate on the types of forms that it
understands.

We dereference the URI and get back a form description. I just made
one up for this scenario, but it would be nice to have a few standard
ones. If could be a HTML one, if that is sufficient.

GET http://myapp.com/rels/create-foo
=>
Cache-Control: private
Content-Type: application/vnd.acme.formdescriptionlanguage+xml

<form-metadata subject="foo" allow="POST" >
<property name="description" required="true" maxlength="24" type="string"/>
<property name="expires" required="false" type="date"/>
<property name="owner" required="false" type="email">
<property name="phone" required="true" type="phone-number">
<!-- Only required if owner is specified -->
</property>
</form-metadata>

The client can use this metadata to drive it's generic form processing
logic. However, it is critical to note that unless this form is going
to be generically rendered to a human who will fill in the form, the
client absolutely must know about the existence of "description",
"expires", etc. Without that knowledge hard-coded into the client, it
cannot fill the form.

So, once our client knows about the existence of those properties then
we are coupled to the content of the form. Which is one of the main
points that Mike and I keep going on about. I accept that the form
does allow us to dynamically change whether a property is required or
not, or in theory the data type of an element, but you cannot rename
"expires" to "dateandtimeofdeath" without breaking the client.

When you drive a web browser with an HTML form you can change property
names, because it is the human can do the translation. If you are
doing code download with your own javascript to process the form then
sure you can update that "client" along with the form. But those are
not the m2m scenarios that we are regularly talking about.

Hard coding a client to perform an update purely based on a rel value
is not that different to using a form. It's true that you specify
default values in a form and round trip those, but you could also put
those default values in the query string. It's not like the client is
going to know about those values to be able to update them.

I fear that by emulating "forms" in hypermedia types that developers
are going to get this false sense of security that they will get the
same flexibility that they have with embedded HTML forms.

To go back to the example, once the client has the form definition,
then it should know how to activate that link and how to process the
response. In this case the form definition says POST to whatever is
in the href and then you are going to get back a representation that
can have the properties, as defined by the form definition.

POST http://myapp.com/foos
=>
Content-Type: application/hal+xml

<resource>
<description>This is the default foo description</description>
</resource>

The representation that comes back can have default values, just like
a HTML form can have default values. The biggest challenge with these
"decoupled" forms is that you need a way to correlate the elements in
the form with their corresponding piece of data in the returned
representation. In this example, I am assuming a simple flat mapping
of form "property" to hal "property". However, in a real form
media-type this definition may need to be more sophisticated.

I guess the main point that I am trying to make with this long winded
post is that I believe there is value to separating reads from writes.
I don't see a need for each hypermedia format to invent its own
mechanism for explaining to the client how to construct a write.
Especially considering the write format is likely a different
media-type in many cases. I think HTML chose to use embedded forms
for a variety of different reasons that are just not as applicable for
the scenarios that we are considering today.

Darrel

[mca]

Darrel:

As I understand this narrative, the only substantial difference here (over a "forms-style" design) is that you make an additional call to get the form.  

There is nothing markedly different about the design of the form or the way clients handle forms (aside from the chance to use conneg to get a form-based media type the client prefers), just that the form is not shipped with responses unless specifically requested.

Do I have that correct?

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

[Gregg Caines]

I think form-as-separate-resource is a fine idea. I hadn't considered
it, and it took some thought, but I think it's totally fine. Maybe
there'd be some json-form content-type for that?

I agree that forms aren't completely evolvable like links are,
especially in pure m2m scenarios. Here's where you get value:

1) Any changes to the form's uri and http method are perfectly safe.
2) Human-facing single-page web apps and native apps that take hints
from the form without understanding the semantics, and render UI
components that a human would fill in. I believe DOJO and YUI have
projects doing this from json-schema based forms.
3) An in-api standard description that client developers can
understand at a glance.
4) Potential for fuzz-testing crawlers

Even then, forms-as-separate-resource are a fine idea. I like it.

G

[Gregg Caines]

This probably sounds crazy, but I think with
forms-as-separate-resource, you also get the possibility for
standardized form subtypes that can be more universally understood
like "report-a-broken-link-form", or "subscribe-to-webhook-form", or
just standard forms for specific media types or microformats like
vcards, ical, adr, etc.

I think it's hard to imagine what machines will and will not be able
to do on their own having never tried this. I agree that today's
client developers are nowhere near ready for this stuff though.

G

[Darrel Miller]

On Wed, Oct 17, 2012 at 8:48 PM, mca <m...@amundsen.com> wrote:
> Darrel:
>
> As I understand this narrative, the only substantial difference here (over a
> "forms-style" design) is that you make an additional call to get the form.
>

That is the only thing that needs to be done differently.

> There is nothing markedly different about the design of the form or the way
> clients handle forms (aside from the chance to use conneg to get a
> form-based media type the client prefers), just that the form is not shipped
> with responses unless specifically requested.
>

The response data will not be embedded in the form, so some kind of
mapping/binding will be necessary to match the data element with its
metadata. Other than that, the forms would work the same way as
embedded ones.

> Do I have that correct?
>

Sure, I suppose I could have saved a whole lot of words if I had said
it that way ;-)

Darrel

[Erik Wilde]

just mentioning from a design perspective: this "form as a separate resource" design is what you almost necessarily end up with when using URI templates. when you fully describe the template, it becomes a template with related descriptions of the additional semantics of the parameters. you can embed this structure everywhere where you're linking to the template-driven resource, or, when it becomes so big that it becomes a bit inconvenient or excessive to do so, you factor it out into its own resource, and then the link links to a URI template, and if you know that one already via caching, you just know what you need to do when you want to follow that link. cheers, dret.

[mca]

LOL!

well, i appreciated the "walk-through" very much. I just wanted to make sure i had the "essence" of the thing.

and yes, the pre-population is "lost" if you use a set of form blocks that are empty (and therefore cache-able).

so, my next assumption is that these pre-built, cache-able forms are not dynamic. IOW, the membership of "user-update" form (i.e. the data inputs, names, etc.) does not vary based on the current user context (admin, guest, etc), but is "fixed" for all contexts. That's why it makes sense to keep them separated and cache-able, right?

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

Darrel

[Darrel Miller]

Erik,

What you are describing sounds a lot like how Open Search works.

Darrel

[Erik Wilde]

that's actually a very neat idea in the context i was just writing about: "URI template modules"

we might actually look into this further, because we do have certain reused concepts across resources, such as the paging ability for feeds and similar things. but then we'd also need those modules to be composable, which might be non-trivial. (how to combine two URI templates?)

cheers,

dret.

[Erik Wilde]

On 17 Oct 2012, at 15:47, Darrel Miller <darrel...@gmail.com> wrote:
> What you are describing sounds a lot like how Open Search works.

it's close, but OpenSearch has a couple things hardcoded that really shouldn't be, so it's not quite the design we're looking for. but you're right that it's close. too bad it's dead.

cheers,

dret.

>
> Darrel
>
> On Wed, Oct 17, 2012 at 9:43 PM, Erik Wilde <dr...@berkeley.edu> wrote:
>> just mentioning from a design perspective: this "form as a separate resource" design is what you almost necessarily end up with when using URI templates. when you fully describe the template, it becomes a template with related descriptions of the additional semantics of the parameters. you can embed this structure everywhere where you're linking to the template-driven resource, or, when it becomes so big that it becomes a bit inconvenient or excessive to do so, you factor it out into its own resource, and then the link links to a URI template, and if you know that one already via caching, you just know what you need to do when you want to follow that link. cheers, dret.
>>
>

[Darrel Miller]

Mike,

On Wed, Oct 17, 2012 at 9:47 PM, mca <m...@amundsen.com> wrote:
> and yes, the pre-population is "lost" if you use a set of form blocks that
> are empty (and therefore cache-able).
>
> so, my next assumption is that these pre-built, cache-able forms are not
> dynamic. IOW, the membership of "user-update" form (i.e. the data inputs,
> names, etc.) does not vary based on the current user context (admin, guest,
> etc), but is "fixed" for all contexts. That's why it makes sense to keep
> them separated and cache-able, right?
>

Hmmm, interesting questions. The peculiarities of my own
implementations are leaking through in my discussion, which is quite
enlightening for me :-)

To answer your first question. For me, I can get default values (or
pre-poulate) because my first POST does not actually create a
resource, it just returns a representation with a default set of
values. I realize that is a somewhat bizarre approach but it makes
more sense in the context of the other funky stuff I do with my
EventSequence media type.

The cached form is fixed in the sense that it is the superset of all
controls for that representation. There are semantics defined in the
form that allow controls to be usable/visible under certain
circumstances and not others. Those circumstances might be based on
the content of the "data" representation.

Not sure if that makes sense, but I tried :-)

Darrel

[Darrel Miller]

Gregg,

On Wed, Oct 17, 2012 at 9:33 PM, Gregg Caines <gr...@caines.ca> wrote:
> This probably sounds crazy, but I think with
> forms-as-separate-resource, you also get the possibility for
> standardized form subtypes that can be more universally understood
> like "report-a-broken-link-form", or "subscribe-to-webhook-form", or
> just standard forms for specific media types or microformats like
> vcards, ical, adr, etc.
>
> I think it's hard to imagine what machines will and will not be able
> to do on their own having never tried this. I agree that today's
> client developers are nowhere near ready for this stuff though.
>
> G

I like that line of thinking :-)

Any movement towards media types with horizontally applicable
semantics would be awesome in my option, regardless of whether they
are read or write media types.

Darrel

[mca]

Darrel:

i have found there are differing use cases when it comes to supporting write-able state transitions.

- cases where the transitions are static at runtime

- cases where the transitions are varying at runtime based on immediate client and/or resource state

VARYING TRANSITIONS

i use "forms-style" when the actual content of any particular form affordance is likely to change at runtime based on "context" (i.e. logged in user, state of the target resource on the server, state of other related items that server must track, etc.).

for example, the "update-invoice" form might have a diff set of inputs if your are an admin than if your are the person who created the invoice. 

also, which members appear in the "update-invoice" form might also be affected by server state such as:

- configuration information stored on the server

- dependent state information from other parties (i.e. shipper or delivery service might not allow edits past certain date/time, etc)

Note I do not have a form for each case described above, just one w/ a varying population of inputs.

STATIC TRANSITIONS

if i have a domain problem where the membership of forms is not going to change (i.e. simple read/write ops that are not bound to user context or varying server state) i am likely to adopt the Atom-style (or HAL-style) approach where the bodies associated w/ write operations are fixed either in source code, client-config, or server resource retrievable by the client at runtime.

I suspect (from going through this w/ you and MikeK) that you rely on static transition defintions and have no use cases for varying transitions.

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

Darrel

[Gregg Caines]

I don't know if others have any stomach for json-schema as a possible
form 'body', but I do think it fits well with the context of json
forms, and it describes a richer structure than x-www-form-url-encoded
with 'required', 'default', and some validations already built in.
There's already a bit of tooling built up around it, so I don't think
it's as heavy-duty as it might sound.

This would also allow you to build forms that completely describe your
GET-able JSON payloads, letting machines do round-trip updates or
copies without transformation to another (flatter) structure.

I've got an example here:
http://caines.ca/blog/programming/hyperjson-a-first-draft/ (ignore
the fact that the form is in-line). Mike Kelly's got another examples
here: https://gist.github.com/3808215 .

G

[Glenn Block]

Wow, that's a long answer.

In terms of redundant form data, yes that is true, but most of  the tagging it is actually redundant and can compress very nicely. I am not saying you MUST choose to embed forms, but OTOH having the forms embedded is actually easier for many clients to process and saves on making additional network calls. For example on a mobile device like a phone, it might actually be cheaper battery wise to send more data in a single chunk than to do successive requests as the cost of making a connection is not free.

As to evolvability, there's different types of evolvability. Yes I agree with forms I can't magically change the key names of existing form elements, like the date example. But I'd also push back that that type of change is FAR less likely. The evolvability I am talking about is new elements are added to the form which newer clients know how to use and older clients ignore. This is exactly the same argument that is used for hypermedia, i.e. I can add new links which newer clients can identify and older clients ignore. And if I take your same argument, I can also break a client reading links if I change the rel from "sv:expires" to "sv:dateandtimeofdath". 

Beyond that with forms, I can target specific forms based on the version of the client (assuming I know their "version"). I can say because you are so and so, here is the form I'll give you. That leads to further evolvability as I can make serious breaking changes and keep older style forms for backward compat.

I like forms because they lead the client. Relying on links leads the client to something that then points them to a specification. Forms lead the client to metadata that it can use to help navigate to the next part of the system.

[Kevin Swiber]

Having started an iterative writing process of a spec for JSON-based hypermedia that follows this approach[1], here are some of the reasons I like "forms":

1) Mutation in the wild: changing the HTTP method, adding input fields, changing input field types.

2) When building clients, there's a bigger focus on adhering to the hypermedia spec than adhering to API documentation.  I need to document less when defining my link relations.  This is important.  This is a difference between getting the client right once for all APIs vs. getting it right for each API I implement.  Yes, the client should handle changes to input field types.

3) There is value in the server communicating expected input field types!  Basic validation is associated with many input field types.  This means the client has the opportunity to prevent a bad request from hitting the server.  We've been doing this for a long time on the Web. I'm somewhat baffled why there's so much resistance when we talk about this in the context of an API.  I see it as a good design that has worked well for Web apps.

In theory, this can sound difficult to a lot of people.  In my experience, it's not _actually_ so hard to do.  (I know… put up or shut up… Still trying to find the time to get examples out there.)

Some feedback I've received:

a) "It's too complicated."  Yes, it can be more complicated, but you pay the tax once instead of over and over and over again.  Personally, I think that's valuable.

b) "Yeah, but if the client doesn't implement the spec correctly, everything breaks."  Certainly.  This has been true for every client-server implementation that has ever existed.  It's not unique to this situation by any stretch.  Even a TCP client breaks if it doesn't adhere to the spec.  It's a risk we all take.

c) "You're never going to need that much flexibility."  I think I will.  It makes me feel warm inside like a personal guarantee or life insurance or Belgian waffles.

So, there are my six cents.  I'm not arrogant enough to claim this is the only way of doing business or that it's even the best for every scenario.  I know that it suits my style and solves the problems I'd like to solve.  That's enough for me, though I am a continuous improvement junkie.  I do really appreciate any input or thought leadership on how to keep getting better.

Good thread.

[1] https://github.com/kevinswiber/siren

Regards,

Kevin Swiber

@kevinswiber

[Mike Kelly]

On Thu, Oct 18, 2012 at 4:04 AM, Glenn Block <glenn...@gmail.com> wrote:
>
> As to evolvability, there's different types of evolvability. Yes I agree
> with forms I can't magically change the key names of existing form elements,
> like the date example. But I'd also push back that that type of change is
> FAR less likely. The evolvability I am talking about is new elements are
> added to the form which newer clients know how to use and older clients
> ignore.

You don't need form controls for this. This happens naturally when you
use the link approach.. old clients are still on the old semantics of
the rel, new clients are on the new semantics.. provided it's not a
breaking change, there's no need to change the rel. If it is a
breaking change this is a problem with both the form and the link
approach.

This is the reason for my push-back on m2m forms.. they _do not_
afford you any significant evolvability benefits that cannot be
achieved via a simpler approach using basic links.

I think the reason that people can't let go of this dream is because
forms are so effective on the human web. But we aren't talking about
the human web. We're talking about machines. Machines aren't people..
they have no intuition.. they are relatively un-dynamic.. they don't
interpret detailed semantics or changes to application flow at run
time. Those are all pivotal aspects which make human forms worthwhile
in terms of cost-benefit.

>
> I like forms because they lead the client. Relying on links leads the client
> to something that then points them to a specification. Forms lead the client
> to metadata that it can use to help navigate to the next part of the system.
>

With respect, that doesn't change much. All you've done here is
describe the way forms work without detailing their value i.e. you
haven't said what actual evolvability behaviours they will afford your
application which _could not_ be achieved with links.

Cheers,
M

[Kevin Swiber]

On Oct 18, 2012, at 3:25 AM, Mike Kelly <mikeke...@gmail.com> wrote:

> On Thu, Oct 18, 2012 at 4:04 AM, Glenn Block <glenn...@gmail.com> wrote:
>>
>> As to evolvability, there's different types of evolvability. Yes I agree
>> with forms I can't magically change the key names of existing form elements,
>> like the date example. But I'd also push back that that type of change is
>> FAR less likely. The evolvability I am talking about is new elements are
>> added to the form which newer clients know how to use and older clients
>> ignore.
>
> You don't need form controls for this. This happens naturally when you
> use the link approach.. old clients are still on the old semantics of
> the rel, new clients are on the new semantics.. provided it's not a
> breaking change, there's no need to change the rel. If it is a
> breaking change this is a problem with both the form and the link
> approach.

The difference here may be subtle, but I think it's important. With the link approach, a client developer has to check the documentation or wait for the "hot new update" e-mail. Hopefully, they see there's cool, new stuff. With the forms approach, they can stumble upon it right in the message even if my well-crafted announcement gets swept into their junk mail.

We do this a lot as software developers. You can either read the big announcements and blog posts about the latest version of your favorite programming language… or you can go right to the REPL and start playing around. I tend to start with the latter.

> This is the reason for my push-back on m2m forms.. they _do not_
> afford you any significant evolvability benefits that cannot be
> achieved via a simpler approach using basic links.

I suppose it depends on what you consider "significant." I prefer to allow the server to offer clients more information about what is acceptable. The client doesn't have to worry about hard-coding HTTP methods, URIs, or input field types (in pure cases). The client can rely on some basic validation before wasting time and resources on a request that will fail. Additions to the interaction are discoverable via the messages. This is significant to me.

> I think the reason that people can't let go of this dream is because
> forms are so effective on the human web. But we aren't talking about
> the human web. We're talking about machines. Machines aren't people..
> they have no intuition.. they are relatively un-dynamic.. they don't
> interpret detailed semantics or changes to application flow at run
> time. Those are all pivotal aspects which make human forms worthwhile
> in terms of cost-benefit.

I agree machines are not humans. I don't think that means we need to be rigid on the interaction requirements we document for clients. Forms are a little looser, a little more dynamic. Gracefully responding to change does facilitate evolvability. The more we put in our API documentation and not in our HTTP responses, the lower our ability to evolve becomes.

I think the primary reason for a lot of anti-forms-over-API claims is that we lack a solid, real-world, public example demonstrating the values. That's one reason I tend to disengage from some of these debates occasionally. I can't disagree with that argument. Right now, we're just experimenting. We'll get there.

Regards,

Kevin

[Mike Kelly]

On Thu, Oct 18, 2012 at 2:22 PM, Kevin Swiber <ksw...@gmail.com> wrote:
>
> On Oct 18, 2012, at 3:25 AM, Mike Kelly <mikeke...@gmail.com> wrote:
>
>> On Thu, Oct 18, 2012 at 4:04 AM, Glenn Block <glenn...@gmail.com> wrote:
>>>
>>> As to evolvability, there's different types of evolvability. Yes I agree
>>> with forms I can't magically change the key names of existing form elements,
>>> like the date example. But I'd also push back that that type of change is
>>> FAR less likely. The evolvability I am talking about is new elements are
>>> added to the form which newer clients know how to use and older clients
>>> ignore.
>>
>> You don't need form controls for this. This happens naturally when you
>> use the link approach.. old clients are still on the old semantics of
>> the rel, new clients are on the new semantics.. provided it's not a
>> breaking change, there's no need to change the rel. If it is a
>> breaking change this is a problem with both the form and the link
>> approach.
>
> The difference here may be subtle, but I think it's important. With the link approach, a client developer has to check the documentation or wait for the "hot new update" e-mail. Hopefully, they see there's cool, new stuff. With the forms approach, they can stumble upon it right in the message even if my well-crafted announcement gets swept into their junk mail.
>
> We do this a lot as software developers. You can either read the big announcements and blog posts about the latest version of your favorite programming language… or you can go right to the REPL and start playing around. I tend to start with the latter.
>

But in reality - people don't update their client because you add new
features.. you update your features because people want to add stuff
to their clients. You're solving a problem that (mostly) doesn't exist
and based on an assumption that developers routinely browse through
APIs more often than they check their email or RSS feeds. That just
doesn't seem realistic to me. It's certainly not convincing enough to
sell me on complicating every write interaction in my API.

>> I think the reason that people can't let go of this dream is because
>> forms are so effective on the human web. But we aren't talking about
>> the human web. We're talking about machines. Machines aren't people..
>> they have no intuition.. they are relatively un-dynamic.. they don't
>> interpret detailed semantics or changes to application flow at run
>> time. Those are all pivotal aspects which make human forms worthwhile
>> in terms of cost-benefit.
>
> I agree machines are not humans. I don't think that means we need to be rigid on the interaction requirements we document for clients. Forms are a little looser, a little more dynamic. Gracefully responding to change does facilitate evolvability. The more we put in our API documentation and not in our HTTP responses, the lower our ability to evolve becomes.
>

And yet we can't seem to find any significant, easily demonstrable
examples of the sorts-of-changes in m2m APIs that forms allow but
links do not.

> I think the primary reason for a lot of anti-forms-over-API claims is that we lack a solid, real-world, public example demonstrating the values. That's one reason I tend to disengage from some of these debates occasionally. I can't disagree with that argument. Right now, we're just experimenting. We'll get there.
>

Judging by the pro-form rhetoric there doesn't seem to be a lack of
trying.. and yet here we still are. I think that should tell us
something.

To be clear - there are uses for form-like controls. I'm trying to
build a business out of one. But I've looked at this for a while now
and it seems to me that the uses are very specific and do not include
your average client-server API.

Cheers,
M

[Gregg Caines]

> And yet we can't seem to find any significant, easily demonstrable
> examples of the sorts-of-changes in m2m APIs that forms allow but
> links do not.

Forms really have all the same safe-change scenarios as uri-templates.
They're basically equivalent, except forms have no expectation of
being side-effect free.

M2M has a few safe changes. An aware client would be fine with:
- a change in uri
- a change in method
- a dropped field
- ignoring optional new fields

There are some opportunities in m2m where the client code doesn't need
to know *anything* about the semantics of the form:
- If these forms are used to auto-generate UI in a thick client like a
1-page web app or a mobile app, the human end-user can do the
interpretation, and it all still works. People are already doing
dynamic UIs based on json-schema for instance.
- fuzz-testing crawlers, like (ape:
http://www.tbray.org/ongoing/When/200x/2006/08/11/Meet-the-Ape )

Also there's the possibility that standard cross-site form types might
develop, so interesting things can happen. A standard webhooks
subscription form type might be a great thing for expanding the use of
webhooks for instance. Other common concerns like
account-registration, account-authentication, payment processing, etc
could benefit from standardization of forms. Machines could do quite
well on completely foreign sites that use standard forms.

And of course just having an in-api standard for humans to be able to
read is reason enough as well. If it's done as a separate resource,
it doesn't have to have any impact whatsoever on the rest of your API
(other than linking to it).

I don't really see the downside, and I know we haven't imagined all
the upsides yet.

G

[Mike Kelly]

On Thu, Oct 18, 2012 at 4:02 PM, Gregg Caines <gr...@caines.ca> wrote:
>> And yet we can't seem to find any significant, easily demonstrable
>> examples of the sorts-of-changes in m2m APIs that forms allow but
>> links do not.
>
> Forms really have all the same safe-change scenarios as uri-templates.
> They're basically equivalent, except forms have no expectation of
> being side-effect free.
>
> M2M has a few safe changes. An aware client would be fine with:
> - a change in uri

Can handle this with links.

> - a change in method

Not that common. Not necessarily straight forward either - changing
from safe to non-safe or idempotent to non-idempotent may not be
respected by the client and could cause problems. In practice you
would probably just introduce the new method as an additional option
in parallel (e.g. use GET unless query string too long in which case
POST), which you can achieve by adding another link.

> - a dropped field
> - ignoring optional new fields

Can handle both of these with links.

> There are some opportunities in m2m where the client code doesn't need
> to know *anything* about the semantics of the form:
> - If these forms are used to auto-generate UI in a thick client like a
> 1-page web app or a mobile app, the human end-user can do the
> interpretation, and it all still works. People are already doing
> dynamic UIs based on json-schema for instance.

Why not use HTML for that?

> - fuzz-testing crawlers, like (ape:
> http://www.tbray.org/ongoing/When/200x/2006/08/11/Meet-the-Ape )
>
> Also there's the possibility that standard cross-site form types might
> develop, so interesting things can happen. A standard webhooks
> subscription form type might be a great thing for expanding the use of
> webhooks for instance.

Right, that is exactly what I am building a business out of
(http://webgun.io). But customised webhook callbacks aren't a typical
client-server interaction.

> Other common concerns like
> account-registration, account-authentication, payment processing, etc
> could benefit from standardization of forms. Machines could do quite
> well on completely foreign sites that use standard forms.

Ok but you could submit "form" for "link relation" and it would be
equally true, plus the solution would be simpler.

> And of course just having an in-api standard for humans to be able to
> read is reason enough as well. If it's done as a separate resource,
> it doesn't have to have any impact whatsoever on the rest of your API
> (other than linking to it).

How does rel documentation not fulfill this criteria?

>
> I don't really see the downside, and I know we haven't imagined all
> the upsides yet.

In which case I'm confused why you don't believe this also applies to
embedded or curies in hal+json..

Cheers,
M

[Glenn Block]

Curious to see your use case. Fair enough that I have not built a large scale application that uses forms where the browser is not involved

However.....the use cases for where I would use forms in a browser seem to match up very well with using them in an API. I have a hard time buying what you are saying, but I am ready to be wrong.

As far as clients adding new features, I am not sure what you mean. It is very common today for example for mobile apps consuming web apis to rev as new features become available in the API. It's not that the client magically evolves by itself, however, let's take the case of an API consumed by Android, IOS and WP7. The app upgrades and WP7 adds a new version right away (I am sure you are laughing now), while IOS and Android lag behind :-). So all the apps continue to function including the older WP7 app until the user decides to upgrade. When the user does upgrade, then they get the newer features. 

M

[Mike Kelly]

On Thu, Oct 18, 2012 at 5:53 PM, Glenn Block <glenn...@gmail.com> wrote:
> Curious to see your use case. Fair enough that I have not built a large
> scale application that uses forms where the browser is not involved

Here it is: http://webgun.io

> However.....the use cases for where I would use forms in a browser seem to
> match up very well with using them in an API. I have a hard time buying what
> you are saying, but I am ready to be wrong.

Buying what? I'm not selling anything! :)

My position here is just to correct statements that say stuff like this:

"you need forms if you want to do writes in a hypermedia API" -
because it is plain wrong.

and this:

"forms give you more evolvability than links in a m2m hypermedia API"
- because so far there isn't much evidence to support this.

Basically, I don't think people should be given the impression that
hypermedia has to be more complicated than it actually is.

Cheers,
M

[Glenn Block]

I never said you _need_ forms nor do I subscribe to that. I do think
they are convenient and not that complicated

[mca]

inline....

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

On Thu, Oct 18, 2012 at 1:22 PM, Mike Kelly <mikeke...@gmail.com> wrote:

On Thu, Oct 18, 2012 at 5:53 PM, Glenn Block <glenn...@gmail.com> wrote:
> Curious to see your use case. Fair enough that I have not built a large
> scale application that uses forms where the browser is not involved

Here it is: http://webgun.io

> However.....the use cases for where I would use forms in a browser seem to
> match up very well with using them in an API. I have a hard time buying what
> you are saying, but I am ready to be wrong.

Buying what? I'm not selling anything! :)

My position here is just to correct statements that say stuff like this:

"you need forms if you want to do writes in a hypermedia API" -
because it is plain wrong.

*****

who is saying "you *need* forms..."?

***** 

and this:

"forms give you more evolvability than links in a m2m hypermedia API"
- because so far there isn't much evidence to support this.

*****

"forms give you *more*..."? not seen that said here. am it missing it?

***** 

Basically, I don't think people should be given the impression that
hypermedia has to be more complicated than it actually is.

*****

+1

****

[Mike Kelly]

>
> On Thu, Oct 18, 2012 at 1:22 PM, Mike Kelly <mikeke...@gmail.com> wrote:
>>
>> On Thu, Oct 18, 2012 at 5:53 PM, Glenn Block <glenn...@gmail.com>
>> wrote:
>> > Curious to see your use case. Fair enough that I have not built a large
>> > scale application that uses forms where the browser is not involved
>>
>> Here it is: http://webgun.io
>>
>> > However.....the use cases for where I would use forms in a browser seem
>> > to
>> > match up very well with using them in an API. I have a hard time buying
>> > what
>> > you are saying, but I am ready to be wrong.
>>
>> Buying what? I'm not selling anything! :)
>>
>> My position here is just to correct statements that say stuff like this:
>>
>> "you need forms if you want to do writes in a hypermedia API" -
>> because it is plain wrong.
>
> *****
> who is saying "you *need* forms..."?
> *****

6 posts in:

"how do you create APIs with json-hal that aren't read-only?"

>>
>>
>> and this:
>>
>> "forms give you more evolvability than links in a m2m hypermedia API"
>> - because so far there isn't much evidence to support this.
>
> *****
> "forms give you *more*..."? not seen that said here. am it missing it?
> *****

OP: "Forms are one of the big missing pieces in hypermedia json formats"

"The [additional] evolvability I am talking about is new elements are

added to the form which newer clients know how to use and older
clients ignore."

There was another thread on another list a week or so ago which
repeated the same sentiments.

Cheers,
M

[mca]

ok, thanks.

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

Cheers,
M

[Gregg Caines]

I think the disagreement is really over whether or not form *content*
(field names, validations, defaults, etc, and NOT uri, method,
content-type, etc) needs to be specified in the api itself, or if it's
suitable to specify it in non-machine-parseable documentation for
humans to interpret and hard-code into clients. If there is no
significant value in making that *content* machine-readable, then
forms are unnecessary because the form envelope could instead be
implemented as a link.

Let me know if I'm mischaracterizing the no-need-for-forms side.

Of course I still think there are a number of reasons to have a
standard for the details of write requirements in json, both for
humans and for programs to interpret on the fly.

I actually don't really even care about forms per se, but
self-descriptive writability just seems to be in the spirit of
hypermedia to me. I browse into / in my API and I can easily see how
to read my way to every resource in the api, so I think there's a
glaring missing symmetry there when there's no in-api way of
specifying how to write. It could just as easily be implemented like
this though:

"_links" : { "somerel" : { "href" : "http://...", "method" : "POST",
"type" : "application/json", "schema" : {... json schema? ... } } }

That actually solves the problem just as well, just by adding a schema
attr to a link, describing the details of what to POST.

If the rel points to a description of the relationship, I could even
put a link to the schema in that description, and not need the
additional 'schema' attr, and still solve my needs I think.

My argument is definitely that it's more interesting when the
*details* of the write are described in the api somehow, and to me at
least seems to be more in the spirit of hypermedia. I haven't seen a
convincing argument why another way would be preferable, but maybe
when I state the position this way (without saying the f-word), we're
already on the same page.

G

[Pat Cappelaere]

Gregg,

I guess there is already a best practice to specify what to POST using JSON-Schema in your API discovery document.
https://developers.google.com/discovery/v1/reference/apis

This keeps your links pretty lean.
Pat.

[Kevin Swiber]

On Oct 18, 2012, at 1:22 PM, Mike Kelly <mikeke...@gmail.com> wrote:

> My position here is just to correct statements that say stuff like this:
>
> "you need forms if you want to do writes in a hypermedia API" -
> because it is plain wrong.
>
> and this:
>
> "forms give you more evolvability than links in a m2m hypermedia API"
> - because so far there isn't much evidence to support this.

Advantages in using forms-like data structures have been mentioned in this thread. You may disagree about their validity, but there is no proof of them being invalid by any means. When it comes to "evidence," I'm not even sure we have enough to claim the REST constraints achieve the desired outcome for Web APIs in general. Once we have a few medium/high traffic Web APIs following the REST constraints, the next step is to wait. After a decade or so, we'll have more information to make a pass/fail assessment of an implementation. Until then, none of us have a leg to stand on when it comes to saying which direction is "right" or "wrong."

> Basically, I don't think people should be given the impression that
> hypermedia has to be more complicated than it actually is.

I don't see anyone who has a goal to make hypermedia more complicated. I see "too complicated!" as an argument against implementation details that others share with the community. That argument repeated over and over gives people the impression hypermedia is complicated. Everyone is entitled to an opinion, but it's the minority who is so outspoken on this as an issue. Frankly, it's bad marketing for hypermedia in general.

We're all still experimenting, and it's too early to call the game. I love talking about this topic in the theoretical zone. The conversations can be engaging, and it's a lot of fun. However, without that element of real-world, time-tested implementation… it's all just words on a page or pictures on a chalkboard. We will all be much wiser 10 years from now. :)


Regards,

Kevin

[mca]

all:

FWIW, i am very much interested in running code.

to pick just a couple examples:

- HAL interests me

- Siren interests me.

- WebGun.io interests me.

while each of these represent significant design effort and reflect the personal opinions/styles/etc. of the authors, these examples interest me because there is running code (lots of it in some cases) associated with these efforts.

discussions about which style is "better" or whether approach "X" is "too Y" or "overly Z" or whether some's POV is just plain wrong carries little weight when I am evaluating these examples.

while i understand ppl want to debate these qualitative issues here, i much prefer seeing discussions here that center on the details of the implementation, the evident results, and the author's thoughts behind the design.

we can all learn from these things w/o publicly passing judgement on whether the work is "right", "better than.." or "worth the effort."

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen

[Glenn Block]

I also am interested in all of the flavors. Different approaches always have their pros and cons. Knowing the strengths / weaknesses helps to think about when to adopt what. Let me make it clear that I am not proposing a black and white view of the world!

[Gregg Caines]

> FWIW, i am very much interested in running code.
>
> to pick just a couple examples:
> - HAL interests me
> - Siren interests me.
> - WebGun.io interests me.

Me too and I totally agree. I've been working on some examples for a
while, and was wondering if anyone else was coming up against the same
issues, or had existing solutions.

This discussion has changed my mind on many key aspects though, so I'm
definitely glad we had it, and glad you pointed me to this list. It
won't be long before I have an example implementation to get more
feedback on if anyone's still interested.

G

On Thu, Oct 18, 2012 at 12:10 PM, mca <m...@amundsen.com> wrote:

[mca]

<snip>

This discussion has changed my mind on many key aspects though, so I'm
definitely glad we had it, and glad you pointed me to this list. 

</snip>

that's good to hear. 

the point of this group is to offer a place were we can talk about our ideas and share our experiments w/o worrying about being told we're "wrong", that our ideas are "silly", etc. that's one of the key values of this group (to me, at least).

and i'm looking forward to hearing more about your project. feel free to share hyour progress and any links any time.

Cheers! 

mca

+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mikeamundsen