Real-life hypermedia API examples ?
137 views
Skip to first unread message
RDahl
Jul 24, 2017, 12:35:03 PM7/24/17
to Hypermedia Web
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 !
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 !
mca
Jul 26, 2017, 11:35:35 PM7/26/17
to hyperme...@googlegroups.com
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.
--
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.
Renaud Dahl
Aug 10, 2017, 11:57:07 AM8/10/17
to hyperme...@googlegroups.com
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 DahlTo unsubscribe from this group and stop receiving emails from it, send an email to hypermedia-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@googlegroups.com.
Mike Amundsen
Aug 10, 2017, 4:15:08 PM8/10/17
to hyperme...@googlegroups.com
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.
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.
Renaud Dahl
Aug 11, 2017, 9:04:51 AM8/11/17
to hyperme...@googlegroups.com
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).
Again, thank you very much,
To unsubscribe from this group and stop receiving emails from it, send an email to hypermedia-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@googlegroups.com.
mca
Aug 11, 2017, 3:24:27 PM8/11/17
to hyperme...@googlegroups.com
" 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.
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.
Martynas Jusevičius
Aug 11, 2017, 5:44:00 PM8/11/17
to hyperme...@googlegroups.com, public-decl...@w3.org
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
To post to this group, send email to hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@googlegroups.com.
Visit this group at https://groups.google.com/group/hypermedia-web.
For more options, visit https://groups.google.com/d/optout.
Mike Amundsen
Aug 11, 2017, 6:54:07 PM8/11/17
to hyperme...@googlegroups.com, public-decl...@w3.org
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?
Martynas Jusevičius
Aug 12, 2017, 4:48:50 AM8/12/17
to hyperme...@googlegroups.com, public-decl...@w3.org
Mike,
https://github.com/AtomGraph/Web-Client
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.
To unsubscribe from this group and stop receiving emails from it, send an email to hypermedia-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
To post to this group, send email to hyperme...@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-we...@googlegroups.com.
Mike Amundsen
Aug 12, 2017, 10:31:07 AM8/12/17
to hyperme...@googlegroups.com, public-decl...@w3.org
thanks.
so, if this client works w/ another server, it needs to be one of your servers? not nay LOD server?
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.
Renaud Dahl
Aug 18, 2017, 4:23:28 AM8/18/17
to hyperme...@googlegroups.com
Once again thank you very much for your answer :)
I'm currently working on extracting the "translator" part of my project and make it a little more generic for my co-workers to be able to use it afterwards. I'll post it here when it's a bit more advanced !But about the message translator pattern, one problem struck me :
if I build my API with a message translator and support for example plain JSON, HAL, Siren and Cj, and clients can choose to use any of these formats, my possibilities for evolution are limited, aren't they ? For example if one of my clients relies on my HAL responses, I can't change my Objects nor my Actions, only my addresses (and that would also break any client who relies on the JSON format only).
if I build my API with a message translator and support for example plain JSON, HAL, Siren and Cj, and clients can choose to use any of these formats, my possibilities for evolution are limited, aren't they ? For example if one of my clients relies on my HAL responses, I can't change my Objects nor my Actions, only my addresses (and that would also break any client who relies on the JSON format only).
In a previous email you wrote "if you expect someone like *me* to use your API, we will be looking for hypermedia in the responses". But if I support HAL, *you* will know that I will never be able to make any changes with Objects and Actions, so why would *you* (still usng *you* as a hypothetical client) ask for any other format ?
There is also the same problem with the other way around : if I support Cj to be able to make changes for all the "OAA" aspects, there is no point in supporting HAL or Siren since they don't deal so well with the "OAA challenge".
With these problems in mind my question is simple : should I really support multiple formats ? And why ?
Thanks (again !)
(BTW, about RESTfest : thank you for suggesting this but I'm working in Paris and won't be able to go to the US in September :( )
To post to this group, send email to hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@googlegroups.com.
Visit this group at https://groups.google.com/group/hypermedia-web.
For more options, visit https://groups.google.com/d/optout.
Martynas Jusevičius
Aug 18, 2017, 4:35:40 AM8/18/17
to hyperme...@googlegroups.com
Mike,
it will work as a Linked Data browser, dereferencing any RDF resources in read-only mode.
But writing will only work for an LDT server.
To post to this group, send email to hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@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 hyperme...@googlegroups.com.
Visit this group at https://groups.google.com/group/hypermedia-web.
For more options, visit https://groups.google.com/d/optout.
mca
Aug 18, 2017, 10:07:00 AM8/18/17
to hyperme...@googlegroups.com
Renaud:
<snip>
if I build my API with a message translator and support for example plain JSON, HAL, Siren and Cj, and clients can choose to use any of these formats, my possibilities for evolution are limited, aren't they ? For example if one of my clients relies on my HAL responses, I can't change my Objects nor my Actions, only my addresses (and that would also break any client who relies on the JSON format only).
</snip>
yes, it is not possible to change the nature of a format when it comes to the amount of meta information available to support change. however you *can* use extensions and/or added-supports to do this along w/ adopting some top-level design rules.
META-INFO
as an example, i want to represent my service response representations in both Cj and HAL and I want to be able to communicate all the meta-info needed to support a generic client (object-addresses-actions). doing this w/ Cj is easy since Cj was designed for this kind of support, but HAL was not designed for this. HAL doesn't include meta-info on objects and actions. so I need a way to carry that meta-info for the HAL representation.
my implementation choice to solve this missing meta-info was to concoct the HAL-FORMS [1] and PODS [2] formats. HAL-FORMS handles the actions and PODS carries the meta-info for objects. the specs contain info on how to write services that output this info and how to write clients to recognize and process this info. (note these are early draft specs that worked for my book and for my local projects and may need additional work to be solid for all desired use cases).
CHANGE-OVER-TIME (COT)
finally, i need to adopt some *patterns* (not specs) on handling change-over-time to make it safer to modify actions and objects. these are
1 - i can't take things away
2 - cannot change the meaning/use of existing data or actions
3 - all additional data/actions must be treated as optional
that means when i want to make a change like break up the field "name" into "givenName" and "familyName", i need to *add* the two new fields w/o taking away the old one:
{
...
"name" : "Mike Amundsen"
...
}
becomes
{
...
"name" : "Mike Amundsen",
"givenName" : "Mike",
"familyName" : "Amundsen",
...
}
If i want to add a new form, i just add a new link-rel in HAL and leave the existing ones, and so forth.
FINALLY
There is no doubt that all this added functionality (HAL-FORMS and PODS) along with adoption of COT patterns is an added burden for both client and server -- a burden that has a cost to weigh against the value of this level of adaptability. it is also worth pointing out that these added support elements are likely to be ignored by most HAL clients. The good news is that even in ignoring the HAL-FORMS and PODS, if you adopt the COT patterns, the existing clients will not break.
hope this helps.
Jeff Michaud
Aug 22, 2017, 2:58:34 PM8/22/17
to Hypermedia Web
Hello Renault,
I don't know about "production" but I have a WIP that may prove useful in exploring a few ideas in Hypermedia. The possibilities should be relatively fathomable and self evident but I'd be happy to get feedback to make it even more approachable.
https://github.com/cometaj2/huckle/blob/master/README.rst
Regards
Jeff Michaud
Filippos Vasilakis
Oct 16, 2017, 7:15:50 AM10/16/17
to Hypermedia Web
Joining the dance a bit late here (what an interesting google group!) but you might be interested taking a look in https://introspected.rest which separates hypermedia and other metadata from the actual data.
Essentially this means that you don't have to do any breaking changes when evolving your API given that each metadata type (like hypermedia etc) is added in a composable way without any breaking changes (fixing your concern #2). It also means that for clients interested only in data, you give them only data, and you serve metadata (like hypermedia) on the side to only those clients really need it and really want it (fixing your concern #1), The concept used for that is MicroTypes and reactive negotiation. You can find a talk explaining some parts of what MicroTypes are capable to offer here ( https://www.youtube.com/watch?v=pc8ZyFjJY4A&t=1s ), though MicroTypes can be more powerful than that, due to time constraints I couldn't dive into the introspection stuff that gives you configuration capabilities per-API for a given MicroType. MicroTypes should solve your last concern #3 (supporting different classes of clients). You can find info about it in https://introspected.rest
I should point out that I had the same objections around the push we see towards hypermedia APIs that is taking place over the last years.
I am not against hypermedias per-se, I do envision a world of unmanned network services that talk to each other without human intervention and hypermedia is the key to that but the way hypermedia is applied in a REST API seems unrealistic and impractical to me.
I should point out that I had the same objections around the push we see towards hypermedia APIs that is taking place over the last years.
I am not against hypermedias per-se, I do envision a world of unmanned network services that talk to each other without human intervention and hypermedia is the key to that but the way hypermedia is applied in a REST API seems unrealistic and impractical to me.
Reply all
Reply to author
Forward
0 new messages