Re: Real-life hypermedia API examples ?

Speaking of patterns.

We have generalized a read-write Linked Data API, i.e. a RESTful CRUD API
with hypermedia support for RDF systems backed by SPARQL:
https://atomgraph.github.io/Linked-Data-Templates/

It is generic in the sense that there is a specification that defines how
the API executes operations, while the actual app-specific operations are
defined declaratively (in an ontology). That is sufficient in order to have
both client and server as generic implementations and store application
logic as data.

We have also implemented an open-source processor as a reference
implementation: https://github.com/AtomGraph/Processor

This is only made possible by the RDF data model because it has a) built-in
URI identifiers b) a standard (query) language for operations

Martynas
CTO
atomgraph.com

On Fri, Aug 11, 2017 at 9:24 PM, mca <mca@amundsen.com> wrote:

> " A plain JSON response is easier to read (for a human) than a Cj
> response... "
> yep - optimizing responses for machines is going to be different than
> optimizing responses for humans. as long as we use the comprehension of
> humans as a guide, we'll be limited in what we allow machines to do.  i'm
> fine w/ not being able to easily read machine code.
>
> yes, most of my work is centered around variations of the WeSTL pattern.
> i've been writing these translators for a few years and WeSTL is the latest
> attempt to create some generic tooling for translators.
>
> I'd love to hear more about your experiences when attempting to
> design/build/use hypermedia-style tooling. feel free to post here anytime.
>
> BTW - what you've been posting here would make great content for the
> upcoming RESTFest in September!
>
> cheers.
>
>
>
> mca
> Mike Amundsen
> +1.859.757.1449 <(859)%20757-1449>
> skype:mca.amundsen
> http://amundsen.com/blog/
> http://twitter.com/mamund
> https://github.com/mamund
> http://linkedin.com/in/mamund
> http://g.mamund.com/meetme
>
>
> On Fri, Aug 11, 2017 at 9:04 AM, Renaud Dahl <renauddahl@gmail.com> wrote:
>
>> Mike,
>>
>> Thank you very much ! Very clear answer.
>>
>> When I mentioned the verbosity of hypermedia formats I didn't really
>> meant the perf costs, I was more concerned about the fact that I might
>> discourage a client developper at first sight. A plain JSON response is
>> easier to read (for a human) than a Cj response...
>>
>> Also, you mentioned a "set of libs that make the extra work trivial", do
>> you mean the representors you use in you RESTful Web Client books code
>> (translating from WeSTL to the media types) ? Or other libs ? (Open source
>> ones maybe ?)
>>
>> Just a couple words about me : I've implemented an API and client to "see
>> for myself" the last couple weeks, and I can agree that using the Message
>> Translator Pattern helps a lot. I started with an existing API in plain
>> JSON, took some time setting up the pattern and adding support for HAL
>> format, but then I could add support for SIREN in less than a day (just the
>> time needed to write the new translator).
>> In the other side I implemented a small script that calls the API a
>> couple times to perform an action and convert it from JSON client to HAL
>> client, then to SIREN client, was also done in less than a day for each new
>> format !
>>
>> Again, thank you very much,
>>
>> Renaud
>>
>>
>> Le jeu. 10 août 2017 à 22:15, Mike Amundsen <mca@amundsen.com> a écrit :
>>
>>> Renaud:
>>>
>>> glad Richardson's talk was helpful. He's a great source of clear
>>> thinking in this space.
>>>
>>> "but adding all thoses extra fields to my responses bloats them"
>>> I've not yet seen any stats that show this "bloat" has any meaningful
>>> perf costs. Jon Moore did a blog post a few years ago that attempted to go
>>> through the costing and found nothing meaningful. IME, The cost of the
>>> network and local disk IO far outweighs the cost of adding metadata to the
>>> message.
>>>
>>> "traditional client developper will ignore the hypermedia format
>>> recommandations and hardcode his URLs like with any other API"
>>> yep. if that's a significant part of your audience and you have no
>>> control over those people, then don't use hypermedia for them. however, i'd
>>> advise not treating the entire *world* like this one type of developer. for
>>> example, if you expect someone like *me* to use your API, we will be
>>> looking for hypermedia in the responses. to make this less emotional,
>>> invest in implementing a message translator (Gregor Hohpe) so that adding
>>> support for another format is not so costly or disruptive. then implement
>>> the formats your community asks for and/or you wish to support.
>>>
>>> "Adding entirely new actions or object properties (or even objects)
>>> will very rarely be supported by the clients"
>>> Separate the worlds of human-driven and machine-driven API consumers.
>>> HTML proves that human-driven responses can add new fields and actions w/o
>>> breaking things -- we've been doing it for 25+ years.
>>>
>>> for machine-driven API consumers, the rules are different. either you
>>> 1 - operate with a single "super" client and a wide vocabulary (e.g.
>>> "accounting" client can do thousands of tasks well into the future)
>>> or
>>> 2 - operate with a lot "mini" clients with a limited vocabulary (e.g.one
>>> client understands "double-entry bookkeeping", another does "invoice",
>>> another does "accounts payable", etc.)
>>>
>>> the machine problem is one of adaptability over time. you can limit this
>>> by limiting the scope of the understood domain.
>>>
>>> either way, you can handle change in the API by writing clients that
>>> ignore things they don't understand and writing services that never take
>>> awy existing promises (fields, actions). clients need to bind to more
>>> abstract elements than "user" and services need to never leak their object
>>> model to the outside world.
>>>
>>> the last book i released (RESTful Web Clients) is about #1. I am
>>> currently working on #2 and hope to release something meaningful in 2018.
>>> Until then, my most recent talk about 12 patterns of hypermedia and
>>> "evolvable services and adaptable clients" gives a preview of this work.
>>>
>>> "I see that I would be able to change some URLs and maybe methods, and
>>> won't have to maintain 2 versions, but are those 2 benefits really enough
>>> to justify the extra work needed to add hypermedia to my APIs ?"
>>> for me , the answer is almost always "yes" -- i have a set of libs that
>>> make the "extra work of hypermedia" quite trivial for me.
>>>
>>> Cheers.
>>>
>>>
>>>
>>> mca
>>> Mike Amundsen
>>> +1.859.757.1449 <(859)%20757-1449>
>>> skype:mca.amundsen
>>> http://amundsen.com/blog/
>>> http://twitter.com/mamund
>>> https://github.com/mamund
>>> http://linkedin.com/in/mamund
>>> http://g.mamund.com/meetme
>>>
>>>
>>> On Thu, Aug 10, 2017 at 11:56 AM, Renaud Dahl <renauddahl@gmail.com>
>>> wrote:
>>>
>>>> Thanks a lot Mike. Leonard Richardson's presentation resonated with
>>>> another talk I watched recently and he does make a fair point.
>>>>
>>>> Any other feedback on the co-workers objections I got ? Here for a
>>>> reminder :
>>>>
>>>> - JSON is widely used because it is easily readable ; but adding all
>>>> thoses extra fields to my responses bloats them, especially with verbose
>>>> formats such as Collection+JSON. If you add that to the fact that client
>>>> developpers aren't used to these formats, don't you think we risk losing
>>>> clients, that would prefer a "traditionnal level-2" API ?
>>>> On the other hand, using a not-so-bloated format such as HAL doesn't
>>>> have as much interest, since as @mamund describes it in his book, it only
>>>> allows changes in addresses and not in objects nor in actions...
>>>>
>>>> - Still talking about this "traditionnal client developper" : he will
>>>> ignore the hypermedia format recommandations and hardcode his URLs like
>>>> with any other API. Then, thinking I used a hypermedia-aware media type, I
>>>> change my URLs. So I have broken a client that would not have been broken
>>>> if I haden't used hypermedia... or am I missing something ?
>>>>
>>>> - Adding entirely new actions or object properties (or even objects)
>>>> will very rarely be supported by the clients. If they are human-driven,
>>>> they won't display anything they don't know about beforehand (since they
>>>> won't know what front-end style is appropriate). Otherwise (scripts,
>>>> agents) they can't know the meaning of newly-added actions/properties and
>>>> won't be able to exploit them... Unless the human developper changes the
>>>> code. So for every new thing added to my API, my clients will have to adapt
>>>> their code if they want to exploit it... which is what they would have done
>>>> if I just put a v2 into production.
>>>> I see that I would be able to change some URLs and maybe methods, and
>>>> won't have to maintain 2 versions, but are those 2 benefits really enough
>>>> to justify the extra work needed to add hypermedia to my APIs ? How often
>>>> do I really need to change a URL / method ?
>>>>
>>>>
>>>> Thanks !
>>>>
>>>> Renaud Dahl
>>>>
>>>>
>>>> Le jeu. 27 juil. 2017 à 05:35, mca <mca@amundsen.com> a écrit :
>>>>
>>>>> RD:
>>>>>
>>>>> check out AWS's API Gateway API and AppStream APIs -- they both
>>>>> support the HAL format
>>>>> Kin Lane may have a list of known hypermedia-centric APIs, too.
>>>>>
>>>>> finally, I think the largest scale project to leverage hypermedia for
>>>>> a wide audience is NYPL's ebook project. One of the key architect's for
>>>>> that project is Leonard Richardson. He did a great RESTFest presentation on
>>>>> his experience w/ hypermedia APIs and his theory on why they haven't seen
>>>>> wide adoption in the for-profit sector (https://vimeo.com/145022543)
>>>>>
>>>>> hope this helps.
>>>>>
>>>>>
>>>>>
>>>>> mca
>>>>> Mike Amundsen
>>>>> +1.859.757.1449 <(859)%20757-1449>
>>>>> skype:mca.amundsen
>>>>> http://amundsen.com/blog/
>>>>> http://twitter.com/mamund
>>>>> https://github.com/mamund
>>>>> http://linkedin.com/in/mamund
>>>>> http://g.mamund.com/meetme
>>>>>
>>>>>
>>>>> On Mon, Jul 24, 2017 at 12:35 PM, RDahl <renauddahl@gmail.com> wrote:
>>>>>
>>>>>> Hello everyone,
>>>>>>
>>>>>> I'm new on this channel (and kinda new in general to the API world),
>>>>>> and very interested about hypermedia APIs. I got a couple questions for you
>>>>>> :
>>>>>>
>>>>>> - Do you know any example of real-life ( = production, real business
>>>>>> case) and idealy open-source hypermedia APIs that you know of ?
>>>>>>
>>>>>> I keep searching but I tend to only find not-open-source APIs, or
>>>>>> APIs that tend to be a little too simple to be really convincing : I love
>>>>>> Maze+XML from Mike Amundsen and also his Tasks API example for his book
>>>>>> RESTful API Clients, but those 2 cases seem a little too simple for me. Any
>>>>>> other example ?
>>>>>>
>>>>>> The objections I get the most when I talk about hypermedia are the
>>>>>> following :
>>>>>> - JSON is widely used because it is easily readable ; but adding all
>>>>>> thoses extra fields to my responses bloats them, especially with verbose
>>>>>> formats such as Collection+JSON. If you add that to the fact that client
>>>>>> developpers aren't used to these formats, don't you think we risk losing
>>>>>> clients, that would prefer a "traditionnal level-2" API ?
>>>>>> On the other hand, using a not-so-bloated format such as HAL doesn't
>>>>>> have as much interest, since as @mamund describes it in his book, it only
>>>>>> allows changes in addresses and not in objects nor in actions...
>>>>>>
>>>>>> - Still talking about this "traditionnal client developper" : he will
>>>>>> ignore the hypermedia format recommandations and hardcode his URLs like
>>>>>> with any other API. Then, thinking I used a hypermedia-aware media type, I
>>>>>> change my URLs. So I have broken a client that would not have been broken
>>>>>> if I haden't used hypermedia... or am I missing something ?
>>>>>>
>>>>>> - Adding entirely new actions or object properties (or even objects)
>>>>>> will very rarely be supported by the clients. If they are human-driven,
>>>>>> they won't display anything they don't know about beforehand (since they
>>>>>> won't know what front-end style is appropriate). Otherwise (scripts,
>>>>>> agents) they can't know the meaning of newly-added actions/properties and
>>>>>> won't be able to exploit them... Unless the human developper changes the
>>>>>> code. So for every new thing added to my API, my clients will have to adapt
>>>>>> their code if they want to exploit it... which is what they would have done
>>>>>> if I just put a v2 into production.
>>>>>> I see that I would be able to change some URLs and maybe methods, and
>>>>>> won't have to maintain 2 versions, but are those 2 benefits really enough
>>>>>> to justify the extra work needed to add hypermedia to my APIs ? How often
>>>>>> do I really need to change a URL / method ?
>>>>>>
>>>>>>
>>>>>> Once again, I'm very interested in hypermedia, those are the only
>>>>>> objections from my co-workers I can't answer yet. That's why I'm asking
>>>>>> here ;)
>>>>>>
>>>>>> Thanks !
>>>>>>
>>>>>>
>>>>>> --
>>>>>> You received this message because you are subscribed to the Google
>>>>>> Groups "Hypermedia Web" group.
>>>>>> To unsubscribe from this group and stop receiving emails from it,
>>>>>> send an email to hypermedia-web+unsubscribe@googlegroups.com.
>>>>>> To post to this group, send email to hypermedia-web@googlegroups.com.
>>>>>> Visit this group at https://groups.google.com/group/hypermedia-web.
>>>>>> For more options, visit https://groups.google.com/d/optout.
>>>>>>
>>>>>
>>>>> --
>>>>> You received this message because you are subscribed to the Google
>>>>> Groups "Hypermedia Web" group.
>>>>> To unsubscribe from this group and stop receiving emails from it, send
>>>>> an email to hypermedia-web+unsubscribe@googlegroups.com.
>>>>> To post to this group, send email to hypermedia-web@googlegroups.com.
>>>>> Visit this group at https://groups.google.com/group/hypermedia-web.
>>>>> For more options, visit https://groups.google.com/d/optout.
>>>>>
>>>> --
>>>> You received this message because you are subscribed to the Google
>>>> Groups "Hypermedia Web" group.
>>>> To unsubscribe from this group and stop receiving emails from it, send
>>>> an email to hypermedia-web+unsubscribe@googlegroups.com.
>>>> To post to this group, send email to hypermedia-web@googlegroups.com.
>>>> Visit this group at https://groups.google.com/group/hypermedia-web.
>>>> For more options, visit https://groups.google.com/d/optout.
>>>>
>>>
>>> --
>>> You received this message because you are subscribed to the Google
>>> Groups "Hypermedia Web" group.
>>> To unsubscribe from this group and stop receiving emails from it, send
>>> an email to hypermedia-web+unsubscribe@googlegroups.com.
>>> To post to this group, send email to hypermedia-web@googlegroups.com.
>>> Visit this group at https://groups.google.com/group/hypermedia-web.
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "Hypermedia Web" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to hypermedia-web+unsubscribe@googlegroups.com.
>> To post to this group, send email to hypermedia-web@googlegroups.com.
>> Visit this group at https://groups.google.com/group/hypermedia-web.
>> For more options, visit https://groups.google.com/d/optout.
>>
>
> --
> You received this message because you are subscribed to the Google Groups
> "Hypermedia Web" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to hypermedia-web+unsubscribe@googlegroups.com.
> To post to this group, send email to hypermedia-web@googlegroups.com.
> Visit this group at https://groups.google.com/group/hypermedia-web.
> For more options, visit https://groups.google.com/d/optout.
>