The header is for the http client to use to deserialize the data stream and the class field is for the app client to use to determine just what kind of representation it is. This has two benefits:
1. Clients to not have to try to catch the HTTP headers to grok the business type. This is good because they may not be using http at all. Rest is an architectural style that lives outside of http.
2. Shared business types need to have a variety of transport mechanisms and formats. Some notable examples around real-world concepts like geospatial, date time and addresses exist as formats in various formats. Another example is the UBL which is used by the EU for intrabusiness transactions.
In the end the client has to be able to identify the business type and locate them in the data they receive. This is harder than it sounds because theses shared types are rarely defined in the same format as the client. The server needs to communicate the format separately so the client knows where to look for the specific properties.
We posted a blog tonight along these same lines: http://www.foxycart.com/blog/the-hypermedia-debate
We're considering Siren for many of the same reasons Matt mentioned. I know everyone's busy, but if you're interested in hashing out this debate for a very specific problem domain (ecommerce), I'd really value your comments on that post.
I'm hoping to build an API that will help the community of API developers. Something people can look at for inspiration and ideas. There may not be a single "right" way to do everything, but if we can find enough best practices in one place, that could go a long way. I know it's what I was looking for 9 months ago.
We don't need more theories or papers, we just need people to design
media types and provide examples of their use.
In the end though these are all just design considerations, which
means it is largely subjective and since every API has different
context, objectives and business drivers there can't be any "right"
answer.
Hi Luke,
I'd be interested to see how you felt the various options in terms of
generic media types played off against one another. Specifically your
thoughts for/against HAL relative to others.
Cheers,
M
On Tue, Sep 25, 2012 at 5:57 AM, Luke Stokes <luke....@gmail.com> wrote:
> I've really enjoyed this thread. Thank you to everyone who participated. I'm missing RESTfest already. :)
>
> We posted a blog tonight along these same lines: http://www.foxycart.com/blog/the-hypermedia-debate
>
> We're considering Siren for many of the same reasons Matt mentioned. I know everyone's busy, but if you're interested in hashing out this debate for a very specific problem domain (ecommerce), I'd really value your comments on that post.
>
> I'm hoping to build an API that will help the community of API developers. Something people can look at for inspiration and ideas. There may not be a single "right" way to do everything, but if we can find enough best practices in one place, that could go a long way. I know it's what I was looking for 9 months ago.
>
> --
> You received this message because you are subscribed to the Google Groups "API Craft" group.
> To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
> Visit this group at http://groups.google.com/group/api-craft?hl=en.
>
>
--
Mike
http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123
--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
Hi Luke,
On Tue, Sep 25, 2012 at 2:49 PM, Luke Stokes <luke....@gmail.com> wrote:
> We like how Siren provides actions because our problem domain involves
> exposing much of our system so hosted content management platforms can
> re-create our entire admin within their interface. Lot's of CRUD, input
> forms, etc. If we build out those actions correctly, it might save them some
> time and allow them to have forms that change overtime as we add new
> features and fields.
Thanks for this, it leaves me with a few more questions:
Have you discussed this with potential implementors at the other end?
Is their front-end going to call out your API for any pages including
these forms?
Is there a reason that these forms could not be served directly as
HTML (i.e. either as text/html or encoded in a string inside a JSON
response)?
On Tue, Sep 25, 2012 at 5:01 PM, Luke Stokes <luke....@gmail.com> wrote:Ok so if your consumers short circuit your forms then you won't be
> On Tuesday, September 25, 2012 10:47:52 AM UTC-5, Mike Kelly wrote:
>>
>> Hi Luke,
>>
>> On Tue, Sep 25, 2012 at 2:49 PM, Luke Stokes <luke....@gmail.com> wrote:
>> > We like how Siren provides actions because our problem domain involves
>> > exposing much of our system so hosted content management platforms can
>> > re-create our entire admin within their interface. Lot's of CRUD, input
>> > forms, etc. If we build out those actions correctly, it might save them
>> > some
>> > time and allow them to have forms that change overtime as we add new
>> > features and fields.
>>
>> Thanks for this, it leaves me with a few more questions:
>>
>> Have you discussed this with potential implementors at the other end?
>> Is their front-end going to call out your API for any pages including
>> these forms?
>
>
> We've discussed it briefly, yes. The initial feedback has been very
> positive. I'm currently thinking about it as a time-saver option for them
> along with a nice way to discover new functionality at run time. They can
> build out their own forms or they can dynamically pull the core pieces from
> us.
gaining any evolvability benefits, since your API will always need to
support the lowest common denominator that is non-form-aware, right?
Are you concerned you that you may be cluttering up your API responses
with these form controls and making them more difficult to read? It is
possible for a formless media type to be time-saving through browsers
that present documentation in-line (the hal browser does this) - you
coud actually have a dummy form in the rel documentation where devs
could input test data.
> Taking this to another level, my business partner is interested inTo clarify; these twig templates are for use in a hosted version of
> letting them customize the forms as full Twig templates. That raises some
> additional concerns to me, but it's something we're exploring. Which leads
> to your next question:
your web app, not relating to the API per se?
>>why wouldn't twig allieviate this for html5/mobile forms in the same way?
>> Is there a reason that these forms could not be served directly as
>> HTML (i.e. either as text/html or encoded in a string inside a JSON
>> response)?
>
>
> We may move that direction, but from what I've seen of form frameworks,
> everyone does things a little differently. As much as I'd like to believe
> there is a single semantic way for how form labels and controls should be
> organized, everyone seems to do things in their own way with their own
> classes and ids. If we provide the whole form layout as is, they may not
> have the flexibility they need.
>
> Our current ecommerce system injects form controls by replacing ^^cart^^ and
> ^^checkout^^ as an example. We tried to follow the CSS Zen Garden approach
> and let people style as needed. For the most part that works, but we still
> ran into situations where people needed something different (which is why
> our last release now supports Twig). With HTML5 and mobile forms, I'm not
> sure locking them into a specific HTML payload will provide the flexibility
> some of our users want.
Well my personal opinion is that the level of dynamism forms
>
> As I said, though, we're definitely exploring it.
>
> As as I just learned in #rest, apparently there's a large debate as to
> whether forms are a good or bad thing, so hopefully we didn't just open
> another can. :) I'll do some more research on that before we make a
> decision.
facilitate is way overblown relative to the sophistication of API
client code. I think your observation that some will not want to dela
with that dynamism is spot on, but has the unfortunate side effect of
writing off forms as a way to improve the evolvability of your API.
I'm not sure that forms improve developer discovery significantly vs
link relation documentation, and I am very much against adding
complexity to an API interface unless absolutely necessary as it just
presents yet-another-thing-you-have-to-be-concerned-about-causing-client-breakage.
That is completely off the top of my head, I should probably write
something up properly some time - hopefully it is coherent enough to
be understandable.
Cheers
M
--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.