Stream: implementers
Topic: FHIR support for REST Hypermedia
Will Jones (Mar 09 2017 at 09:52):
What, if any infrastructure, does FHIR provide for support of hypermedia? Especially in the REST level 3 sense.
Grahame Grieve (Mar 09 2017 at 10:36):
can you clarify?
Lloyd McKenzie (Mar 09 2017 at 14:38):
@Will Jones No built-in support, though I guess in theory you could use extensions. With FHIR, the set of possible operations is declared in advance and is exposed on the server in a generic way using the CapabilityStatement. No one's brought forward the use-case to provide a more constrained set of context-specific capabilities in the instances. Can you share your use case(s)?
Will Jones (Mar 09 2017 at 15:09):
The reason for my query is that there are some REST Maturity (Richardson Level 3 - HyperMedia) evangelists in CSC working mainly in the Insurance sector who are on a mission to get Hypermedia into the standard reference architecture for APIs in groups like OpenAPI and indeed FHIR. So my answer is that it is limited but extensions are the route to Richardson Level 3 and true RESTfulness for FHIR. :) Thanks
Jens Villadsen (Mar 09 2017 at 15:23):
I only know what I just read about Richardson Lvl. 3 on https://martinfowler.com/articles/richardsonMaturityModel.html#level3, but the statement "The point of hypermedia controls is that they tell us what we can do next, and the URI of the resource we need to manipulate to do it. Rather than us having to know where to post our appointment request, the hypermedia controls in the response tell us how to do it." seems a bit conflicting towards the 'spec first' approach given in IG's and structuredefs - but I could be mistaken.
Lloyd McKenzie (Mar 09 2017 at 17:05):
From the examples, there'd have to be pre-coordinated understanding of the meaning of the link types (so the software would understand what a given link would actually do). If you've got that level of agreement with FHIR, then you've also got knowledge of what the link needs to look like without it needing to appear in the instance. So my read is that the hypermedia approach works best when there's standardization of the link semantics, but not the URLs. FHIR standardizes the URLs
Geoff Low (Mar 09 2017 at 18:55):
From the trenches, hypermedia is a painful experience for people attempting to implement it and use it - switching to Swagger has yielded much more in considerably less time. Not that I am of any import, but I'd put it squarely on the nice-to-have queue.
Grahame Grieve (Mar 09 2017 at 19:18):
we do use hypermedia in places. You can see that on my server in that it adorns resource responses with link to html editing etc. But as Lloyd says, that's only meaningful if you know what the links mean, and so far, we haven't had use cases brought to the spec that make standardising this worth while. But if you have an internal specification, then you can mark up the http responses as you wish
Thomas Lukasik (Mar 09 2017 at 22:34):
I believe that what @Will Jones and @Jens Villadsen are referring to are statements made by Fielding himself to clarify HATEOS ("Hypermedia as the Engine of Application State"), specifically about not relying on "fixed resource names or hierarchies" (read: FHIR Resource names) and/or "out-of-band information, such as a domain-specific standard" (read: a healthcare specific standard like FHIR) if you want to call your API "RESTful".
The main points that Fielding made in that post about what (I believe) we're discussing here are excerpted below:
A REST API must not define fixed resource names or hierarchies .. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC’s functional coupling].
A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client.
A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API).. [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
You can read the entire post here: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
Thomas
Lloyd McKenzie (Mar 09 2017 at 22:49):
Yes, but that runs counter to the whole standardization objective of HL7 - where we want both the data and the invocation mechanisms to be the same across servers so as to maximize interoperability and reduce costs.
Jens Villadsen (Mar 09 2017 at 23:17):
@Lloyd McKenzie - It would be funny to ask Roy Fielding about whether he thinks FHIR is RESTful or not ;)
Thomas Lukasik (Mar 09 2017 at 23:58):
@Lloyd McKenzie While I don't disagree that a truly RESTful API would be in conflict with the objectives of FHIR, I do question the need to say that the FHIR API is RESTful if it's really not. Is it just an attempt at "marketing" FHIR to contemporary developers? The FHIR API would be just as useful, and work just as well, if we simply called it a Web API and avoided running afoul of the REST purists.
Thomas Lukasik (Mar 10 2017 at 00:00):
@Jens Villadsen Based on the tone and strength of his HATEOS post, I think he would not:
"I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating."
"What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?"
Grahame Grieve (Mar 10 2017 at 00:07):
it's not a REST API because of this. But it's RESTful in that we conform to other aspects of REST, and pretty meaningfully. And it's RESTful in that we conform to mainstream expectations of what a RESTful interface looks like
Thomas Lukasik (Mar 10 2017 at 00:50):
@Grahame Grieve RE "And it's RESTful in that we conform to mainstream expectations of what a RESTful interface looks like"
I believe that it's more correct to say that the FHIR API conforms to mainstream expectations of what a "Web API" looks like.
Fielding based hist REST thesis on the Web (the first four words of his theses being "The World Wide Web", and the first paragraph stating the motivation for his paper as: "In order to identify those aspects of the Web that needed improvement and avoid undesirable modifications, a model for the modern Web architecture was needed to guide its design, definition, and deployment.").
Because of this, a Web API naturally "looks like" a REST API, but it's not how it looks, it's how it works that determines whether it's a REST API or not. And Fielding himself has stated very strongly that "..if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period."
And to be clear here, I'm not condemning the use of "RESTful" when referring to FHIR's Web API, I'm only attempting to explain what @Will Jones "REST Maturity (Richardson Level 3 - HyperMedia) evangelists" may have been getting at when they took issue with FHIR's REST claims.
Lloyd McKenzie (Mar 10 2017 at 01:38):
FHIR qualifies as maturity level 2. There's nothing in it that would stop you from being conformant with level 3 if you really wanted to, but it's not clear what you'd gain that would make the effort worth it given what the FHIR standard already dictates.
Thomas Lukasik (Mar 10 2017 at 02:21):
I don't know, @Lloyd McKenzie .. maybe just the same kind of satisfaction that a DBA gets from being able to say that his database is in 6th normal form? :-)
Jens Villadsen (Mar 10 2017 at 08:03):
In that case, anywhere where FHIR is mentioned as a RESTful api in the documentation, it should be corrected to RESTful API RMM (Richardson Maturity Model) L2 - or what? It is my personal experience that all API's I've been confronted with that have claimed RESTful compliance have meant RMM L2. It is my honest belief that such a statement (RMM L2) brings little clarification to the target audience (even though the little devil engineer standing on my shoulder says otherwise saying that statemetns should be as exact as possible).
Thomas Lukasik (Mar 10 2017 at 12:23):
@Jens Villadsen .. it seems that Fielding has declared (and others agree) that ONLY Level 3 gets you "RESTful".. and anything less is just not REST.. as summed up in this related post:
..by Roy’s strict criteria, hypermedia is a precondition of REST.
Anything else should not call itself REST.
So the maturity model actually looks like this:Level One : not REST
Level Two : not REST
Level Three : RESTThat’s why I’ve been realizing more and more that the last three years have been a big waste spinning circles around URIs and verbs.
Spending time to graduate to level one or two of the maturity model is a huge waste of time, because if you want to be RESTful, you have to start at level three.
Hypermedia is a constraint — it’s a precondition to getting into the REST stadium.
If you're interested, the full post can be read at: https://looselyconnected.wordpress.com/2011/03/09/the-richardson-maturity-model-of-rest-and-roy-fielding/
Lloyd McKenzie (Mar 10 2017 at 15:56):
So the issue is that industry at large uses the term RESTful to refer to things that aren't necessarily level 3 but the authorities on REST don't consider to be proper REST. And, as far as I know, there's no other agreed term to use for level 1/2 systems. The second issue is that it's not terribly clear why, in our space, there'd be any point to trying to get to level 3 and thus qualifying as REST according to the official definition. Can anyone present a reason why going to level 3 would make sense? Or a more appropriate descriptive label that would still make sense to industry?
John Moehrke (Mar 10 2017 at 16:25):
There is no use in engaging with the religion of RESTful zealots. Their religion is not a standard, it is just a whitepaper. Thus it requires a high priest to interpret and pontificate. We are as close as any real-world implementer cares. We are focused on real-world use, not religion.
Thomas Lukasik (Mar 10 2017 at 16:36):
@Lloyd McKenzie I think that in order to answer your question we would first have to decide whether or not we can even consider Level 1 and Level 2 as valid REST.
If we accept Fielding's (highly qualified) position that they are not, then speaking of Level 1 and Level 2 REST is really meaningless, so the question becomes "Is there any benefit or reason to make FHIR API RESTful, or is it better to simply accept that it's simply a Web API, and call it that."
Nothing about FHIR would change other than the documentation and conversation.
Lloyd McKenzie (Mar 10 2017 at 16:46):
There are all sorts of web interfaces that are possible. FHIR's is a particular style of web interface that is understood by most implementers to be "RESTful". I don't want to go to an ultra-generic term that's not going to make clear to implementers what we do. At the same time, we don't want to mislead implementers about what we're actually doing.
Thomas Lukasik (Mar 10 2017 at 16:56):
@John Moehrke RE "We are focused on real-world use, not religion."
If that's really the case, then why the fetish for using the religious term REST when describing FHIR? That's like telling everyone you're Catholic because Catholics are popular, when in reality you haven't been Baptized. Having the RESTful label doesn't make FHIR any better, does it? And If it's "just a whitepaper", then why is it so important to pretend that FHIR is in compliance with it?
How would the FHIR community feel if all sorts of non-compliant interfaces started calling themselves FHIR APIs? Think about that for a second. If an implementation doesn't comply with the FHIR specification, then it's not FHIR, and if Fielding says that FHIR has no right to call itself RESTful unless it's at Level 3, then FHIR isn't RESTful. End of story.
John Moehrke (Mar 10 2017 at 17:00):
@Thomas Lukasik FHIR is being developed by a recognized SDO; so it will be a "Standard". REST is a useful pattern, that is recognized as a pattern. I think we are following that pattern appropriately. Expressing our intent relative to the RESTful pattern is helpful to our readers. But given that it is just an informative pattern, all we can do is 'think' or 'believe'. This is the fundamental difference between a standard and a religion.
Thomas Lukasik (Mar 10 2017 at 17:03):
@John Moehrke RE "I think we are following that pattern appropriately"
You think we are, but the sole authority on what is or isn't RESTful thinks we're not. I guess it's a tie.
Thomas Lukasik (Mar 10 2017 at 17:29):
@Will Jones RE "So my answer is .. extensions are the route to Richardson Level 3 and true RESTfulness for FHIR."
Have you given this any further thought to acting on this answer? I'm trying to imagine how the FHIR extension mechanism -- which is intended to extend individual FHIR resources -- could be used to implement a hypermedia driven API.
Now that's not to say that I think it isn't possible, it's only that it's not immediately clear to me how the FHIR extension mechanism could be used to implement a FHIR API that reaches REST Maturity (Richardson Level 3 - HyperMedia), so if you're willing to share, I'd really appreciate hearing about any success that you have in taking that approach.
And @Lloyd McKenzie since this approach was suggested by you, I'd also very much appreciate it if you'd be willing to throw a few hints my way.. maybe a very simple "Hello World" example.
Thanks,
@Thomas Lukasik
Lloyd McKenzie (Mar 10 2017 at 17:44):
@Thomas Lukasik Level 3 simply means that instances will include coded links with the URLs allowing particular operations to be invoked on the resource. You could define an extension on a resource that would allow such a pair of URLs to be sent - so every patient instance could include links with the URLs for the operations that can be performed on that resource. Why you'd want to - I have no clue.
Jens Villadsen (Mar 10 2017 at 18:06):
It seems to me that FHIR is not all that tailor-fit for a 'true' RESTful API. Where one should not make many assumptions up front when using true RESTful API's as it should be possible for the client understand what options are available at runtime, FHIR interfaces, implementations guides and what not are usually dissected ahead of putting systems together. But also, as long as one specs the FHIR interfaces upfront, it seems of little value to try achieve a true RESTful API.
Jens Villadsen (Mar 10 2017 at 18:10):
@John Moehrke an even if FHIR is being developed by a recognized SDO, it still does not make the standard or the content of it flawless. It might be true to say FHIR is inspired by REST, but it does not follow it strictly.
Thomas Lukasik (Mar 10 2017 at 18:27):
@Lloyd McKenzie RE "Why you'd want to - I have no clue"
I think the answer to your question lies in the need for a truly RESTful API to comply with several other REST constraints that were described by Fielding on his blog, such as:
"A REST API must not define fixed resource names or hierarchies.."
"A REST API should never have “typed” resources that are significant to the client..", and
"A REST API should be entered with no prior knowledge beyond the initial URI"
A truly RESTful API adhering to these constraints would be hard-pressed to provide any kind of functional request/response behavior in the absence of those (seemingly useless) links, which only seem useless in the context of your answer because FHIR (being a standard) violates all 3 of the aforementioned REST constraints, and FHIR clients only "know what to do next" because "what can be done next" can be determined (or is pre-determined) by having "prior knowledge" of the FHIR standard protocols.
Otherwise, a client would need those "links with the URLs for the operations that can be performed on that resource" because those links would (should) be the only things driving what could happen next in a truly "hypermedia driven" (a/k/a RESTful) API.
I think this helps to illustrate what you yourself stated, @Lloyd McKenzie -- that true RESTful behavior "runs counter to the whole standardization objective of HL7", and that an API based on pre-defined knowledge of a standard specification is pretty much in complete conflict with not only the rules, but the very idea, of REST.
John Moehrke (Mar 10 2017 at 18:45):
so then... what problem needs to be solved? It seems like circular argument (not unlike any other religion)
John Moehrke (Mar 10 2017 at 18:47):
I will point out that with FHIR you can start with knowing only the server URL. as there is defined behavior for querying the root, and includes capabilities declarations. Not that I think this solves that problem, but it is far more than any other web-api seen
Grahame Grieve (Mar 10 2017 at 18:53):
so I've decided to say something about this:
"A REST API must not define fixed resource names or hierarchies.."
"A REST API should never have “typed” resources that are significant to the client..", and
"A REST API should be entered with no prior knowledge beyond the initial URI"
Grahame Grieve (Mar 10 2017 at 18:54):
what I recall was, "unless these are declared in a mime type".
nicola (RIO/SS) (Mar 10 2017 at 18:54):
@Thomas Lukasik how would you update FHIR to be RESTful? Links in Conformance and Resource's references?
Grahame Grieve (Mar 10 2017 at 18:54):
otherwise, you can't actually use content. like xhtml
Thomas Lukasik (Mar 10 2017 at 18:55):
Honestly, @John Moehrke I don't think that there's an immediate problem that needs to be solved.
The whole conversation began because @Will Jones asked about FHIR hypermedia support in connection with REST Maturity (Richardson Level 3 - HyperMedia) compliance. The rest (no pun intended) of the conversation just developed from that point.
Grahame Grieve (Mar 10 2017 at 18:55):
on the wider subject, I don't care if the high priests say you can't use 'RESTful' for level 2, when the rest of the world is anyway. And "web API' also describes levels 0 - 2.
Grahame Grieve (Mar 10 2017 at 18:56):
we have several implementations that use hypermedia to extend their implementations beyond what is described for the FHIR media type - that is, for API extensions.
Grahame Grieve (Mar 10 2017 at 18:57):
perhaps I should add a section about that to the specification to help people understnd that
nicola (RIO/SS) (Mar 10 2017 at 18:57):
hypermedia driven client still need some meta-data conventions to navigate hyper controls
Grahame Grieve (Mar 10 2017 at 18:58):
but apparrently you aren't allowed to make any ;-)
nicola (RIO/SS) (Mar 10 2017 at 18:59):
Another concern, i see, FHIR Resource could exist out of server or on many servers - we should be able to replicate data from one server to another - so we need hypemedia striped version of data - how do this play with REST?
nicola (RIO/SS) (Mar 10 2017 at 19:02):
Why something like swagger is not REST? FHIR Conformance could be converted to swagger. For me it's question - should we mix metadata with data or not?
Thomas Lukasik (Mar 10 2017 at 19:10):
@nicola (RIO) RE "how would you update FHIR to by RESTful?"
I don't have an answer to that because I don't think that it's possible to do so, since FHIR (by virtue of it being a standard) relies on "fixed Resource names and hierarchies", "typed Resources", and "prior knowledge beyond an initial URI" -- all things that are prohibited in a truly RESTful API.
The focus of my posts was only that FHIR is not RESTful because it breaks so many rules. I never even suggested that it could be made RESTful.
nicola (RIO/SS) (Mar 10 2017 at 19:21):
@Thomas Lukasik If you start your jorney into FHIR server thro Conformance (or Swagger file) - this end-point provides you with links to navigate, so there is no hardcoded resource names etc. You could think about FHIR uri temlates like recomendations :) We could create Hypermedia format for resources, where we will replace all references with links and provide links to operations like update/patch/delete etc (like in search bundle paging). To be honest i like swagger manifest more then FHIR CapabilityStmt, because it's more generic and extensible (i.e. allows to add additional endpoints). FHIR Capability Statement looks like condensed variant, with weak support for additional operations.
nicola (RIO/SS) (Mar 10 2017 at 19:28):
FHIR uri's is good convention (over configuration :) for one server, because freedom is evil :) But in case of distributed system hyper controls will help - for example Patients live on one domain and Physicians on another and you could discover it from manifest
Thomas Lukasik (Mar 10 2017 at 21:14):
@nicola (RIO) I'm not 100% sure where you're going with your last post, and perhaps I'm reading too much into it, but it sounds like you're saying that you believe it's possible to overcome the tensions between REST principles and those of a standard (like FHIR) in order to implement a FHIR REST API that even Fielding would approve of. Is that even close to what you're suggesting, or am I misunderstanding you?
Lloyd McKenzie (Mar 10 2017 at 21:31):
My interpretation of the situation is as follows: Fielding invented a term, but the term has come into common use in a broader way than he might wish. FHIR aligns with the broader usage, but not Fielding's specific intent. We (HL7) don't necessarily care that much about Fielding's specific intent, we care about communicating with broad industry and doing what's useful to broad industry. So my leaning is to add something like this somewhere in the spec: "FHIR is described as a RESTful specification based on common industry level use of the term REST. In practice, FHIR only supports level 2 on the [link REST Maturity scale] as part of the core specification, though full level 3 conformance is possible through the use of extensions. Because FHIR is a standard, it does rely on standardization of resource structures and interfaces which may be considered a violation of some REST principles, but is key to ensuring consistent interoperability."
nicola (RIO/SS) (Mar 10 2017 at 21:45):
Why no ask Fielding?
nicola (RIO/SS) (Mar 10 2017 at 21:53):
@Thomas Lukasik Yes, i think so - FHIR could be easyly converted into 100% RESTfull API :)
nicola (RIO/SS) (Mar 10 2017 at 22:16):
HATEOAS was very successfull for WWW, i think, it's not so critical for API's, until we start building distributed systems on top of FHIR. At that time discoverability and hypermedia elements (Level of indirection) will be helpful and will be added to FHIR :)
Thomas Lukasik (Mar 10 2017 at 22:23):
@Lloyd McKenzie I think that adding a clarifying disclaimer in the documentation would go a long way towards addressing the issue, and I like your rough draft example.. short and to the point.
Thomas Lukasik (Mar 11 2017 at 06:08):
RE @nicola (RIO) : "hypermedia driven client still need some meta-data conventions to navigate hyper controls"
RE @Grahame Grieve : "but apparently you aren't allowed to make any ;-)"
It just occurred to me that these two comments shed light on the problem (apologies, @John Moehrke .. I guess there was one after all) that we're dealing with, which is that:
"pure" REST is aligned with "casual" interactions.. specifically, the kind you engage in when interacting with a Web page, which makes sense given that Fielding literally "backed into" REST by analyzing and reverse-engineering the behavior of the World Wide Web in his thesis.
"FHIR style" REST (forgive me RESTafarians) is aligned with "formal" interactions.. specifically, the kind you engage in when interacting with a Web application, which also makes sense given that FHIR was "reverse engineered" from the experiences of implementing mission critical (and for the most part non-HTTP based) HL7 v2 and v3 software systems.
So it's essentially just a "culture clash".
Because of the difference between where both have come from and where both are headed, REST and FHIR simply don't mix well, so if we're going to force them together we should expect issues like the one that @Grahame Grieve and @nicola (RIO) have very neatly exposed in their brief exchange.
Abbie Watson (Mar 11 2017 at 15:39):
We've had a similar culture clash in the Meteor ecosystem, between tool developers and tool adopters. One notable example was the Deps API. For the people developing the tools, the functionality obviously managed the dependencies necessary to render a GUI component. But since it encapsulated and hid the dependency tracker, the API name was completely opaque to people using the tools, who were only concerned with it's end results, not how it achieved the results. The API was eventually renamed Tracker. The point being, that consumers of APIs often have different interpretations of what an API is used for than the producers of said APIs.
To that extent, it also occurs to me that FHIR sort of represents an 8th "Business Level" to the tradition 7 layer OSI model.
Brian Postlethwaite (Mar 14 2017 at 23:39):
I like that text Lloyd, nicely worded.
Lloyd McKenzie (Mar 15 2017 at 01:20):
Ok, I've added this text (more or less) as the first paragraph on the http page. Hopefully that will help clarify things for readers.
Paul Knapp (Mar 15 2017 at 09:29):
Shouldn't hypermedia be represented as metadata rather than extensions as the suite of available operations does not redefine the resource contents it proposes what may be done with the resource as it is?
Lloyd McKenzie (Mar 15 2017 at 14:45):
Extensions can be metadata. Extensions are appropriate because this is not something most FHIR implementers need/do.
Paul Knapp (Mar 15 2017 at 15:52):
You can put extensions in Resource.meta? I did not realize that.
Lloyd McKenzie (Mar 15 2017 at 16:03):
meta is an Element, so it inherits extension. You can put extensions there that you wouldn't want to be included in signatures - and I agree that links expressing what operations can be performed on the resource would probably fall into the category of "things you shouldn't sign". If there's interest, we could put together a section on doing level 3 REST in FHIR and talk about such things - possibly even standardize the extensions. But that'd be an R4 exercise.
Last updated: Apr 12 2022 at 19:14 UTC
