Re: Real-life hypermedia API examples ?

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