Re: Real-life hypermedia API examples ?

thanks.

so, if this client works w/ another server, it needs to be one of your
servers? not nay LOD server?


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 Sat, Aug 12, 2017 at 4:48 AM, Martynas Jusevičius <martynas@atomgraph.com
> wrote:

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