Re: Real-life hypermedia API examples ?

Mike,

the client implementation is here:

https://github.com/AtomGraph/Web-Client

I'll get back to you re. servers, I need to check if we have public apps
available.

On Sat, 12 Aug 2017 at 00.54, Mike Amundsen <mca@amundsen.com> wrote:

> Martynas:
>
> might have mis-read the links, but can you point me to a generic client
> implementation? and a couple servers that the client can interact with?
>
>
>
> mca
> Mike Amundsen
> +1.859.757.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 5:43 PM, Martynas Jusevičius <
> martynas@atomgraph.com> wrote:
>
>> 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.
>>>
>>
>> --
>> 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.
>