What you're describing, getting available operations at "client implementation time", is indeed not HATEOAS and is not the purpose of OHM. For this there is the static "links" field of OpenAPI.
As I tried to say in the blog, HATEOAS is not a good fit for external applications using the API as a library since the application state is not in the API but in the client consuming it.
So generally you would use HATEOAS for your own web applications, not for external ones and not for micro-services.
For documentation, the advantage is providing navigability of the doc which can bring more context than the "links" object of OpenAPI.
Also, one of the advantages I'm seeing on the project I'm working on is that with the OHM-browser, we can provide a usable UI for the application before the front-end is ready.
I have to agree with Paulo here and I think you're mistaken about HATEOAS. Getting available operations at "client implementation time" is most certainly HATEOAS as the client MUST understand the hypermedia in order to do anything with it. You even said it yourself in the blog post with "Another advantage of using REST and OHM for Web services is that you can provide an endpoint that lists all the possible operations that are available for clients." You say HATEOAS is not a good fit for external applications, but that is what all the web is. The browser is a client for the HTTP protocol, and how many different browsers exist? There is an excellent talk by Jim Webber about REST application design at vimeo.com/41763224.
Swagger, and by extension OHM are too focused on the PATH. The PATH should be opaque to the client. A server should be able to change all it's URL's to GUID's and not break any clients. It's the resources and the link relations that tie them together that is important. A great example of REST documentation is the Amazon API Gateway rest API docs. It uses HAL+json as it's media type and defines the resources, link relations, and starting api endpoint.
Getting available operations at "client implementation time" is most certainly HATEOAS
Sorry but I can't agree with that. HATEOAS provides affordances through links dynamically at runtime, not statically at client implementation.
Swagger, and by extension OHM are too focused on the PATH. The PATH should be opaque to the client.
The "PATH" is opaque in OHM. Look at the OHM-browser : it doesn't know any path before using the application.
It uses HAL+json as it's media type and defines the resources, link relations, and starting api endpoint.
You can totally do the same with OHM. The advantage is that OHM supports all H-Factors whereas HAL supports only a few. HAL supports only navigation links through GET. OHM supports all types of operation, can describe forms, etc...
Sorry but I can't agree with that. HATEOAS provides affordances through links dynamically at runtime, not statically at client implementation.
I agree with that. What I was trying to say is that the client still needs to be able to understand what those opaque links represent by knowing at implementation time the set possible of link relations it MIGHT encounter. Not that it's preprogrammed with the workflow steps/navigation, but if it sees a "next" or "user-disable" link relation, it knows how to proceed/present that affordance to the user.
OHM supports all types of operation, can describe forms, etc
I must have missed this piece, is OHM meant for documentation or are you proposing it as an implementation hypermedia type?
Not that it's preprogrammed with the workflow steps/navigation, but if it sees a "next" or "user-disable" link relation, it knows how to proceed/present that affordance to the user.
That's the semantic of the application that must be a shared understanding between the application and the user-agent. In HTML, that's generally human language. In OHM there are several possibilities : for humans (or any intelligent form), you can use the "summary" and "description" fields of the operations ; for computers (or anything with a limited vocabulary) you can use the "operationId" field of the operation. As said in the post, OHM doesn't define a vocabulary so you need to define your own or reuse an existing one.
is OHM meant for documentation or are you proposing it as an implementation hypermedia type?
It's an Hypermedia type. I thought it was clear in the title. Apparently not... 😅
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Hi Paulo,
What you're describing, getting available operations at "client implementation time", is indeed not HATEOAS and is not the purpose of OHM. For this there is the static "links" field of OpenAPI.
As I tried to say in the blog, HATEOAS is not a good fit for external applications using the API as a library since the application state is not in the API but in the client consuming it.
So generally you would use HATEOAS for your own web applications, not for external ones and not for micro-services.
For documentation, the advantage is providing navigability of the doc which can bring more context than the "links" object of OpenAPI.
Also, one of the advantages I'm seeing on the project I'm working on is that with the OHM-browser, we can provide a usable UI for the application before the front-end is ready.
I have to agree with Paulo here and I think you're mistaken about HATEOAS.
Getting available operations at "client implementation time"is most certainly HATEOAS as the client MUST understand the hypermedia in order to do anything with it. You even said it yourself in the blog post with "Another advantage of using REST and OHM for Web services is that you can provide an endpoint that lists all the possible operations that are available for clients." You say HATEOAS is not a good fit for external applications, but that is what all the web is. The browser is a client for the HTTP protocol, and how many different browsers exist? There is an excellent talk by Jim Webber about REST application design at vimeo.com/41763224.Swagger, and by extension OHM are too focused on the PATH. The PATH should be opaque to the client. A server should be able to change all it's URL's to GUID's and not break any clients. It's the resources and the link relations that tie them together that is important. A great example of REST documentation is the Amazon API Gateway rest API docs. It uses HAL+json as it's media type and defines the resources, link relations, and starting api endpoint.
Sorry but I can't agree with that. HATEOAS provides affordances through links dynamically at runtime, not statically at client implementation.
The "PATH" is opaque in OHM. Look at the OHM-browser : it doesn't know any path before using the application.
You can totally do the same with OHM. The advantage is that OHM supports all H-Factors whereas HAL supports only a few. HAL supports only navigation links through GET. OHM supports all types of operation, can describe forms, etc...
I agree with that. What I was trying to say is that the client still needs to be able to understand what those opaque links represent by knowing at implementation time the set possible of link relations it MIGHT encounter. Not that it's preprogrammed with the workflow steps/navigation, but if it sees a "next" or "user-disable" link relation, it knows how to proceed/present that affordance to the user.
I must have missed this piece, is OHM meant for documentation or are you proposing it as an implementation hypermedia type?
That's the semantic of the application that must be a shared understanding between the application and the user-agent. In HTML, that's generally human language. In OHM there are several possibilities : for humans (or any intelligent form), you can use the "summary" and "description" fields of the operations ; for computers (or anything with a limited vocabulary) you can use the "operationId" field of the operation. As said in the post, OHM doesn't define a vocabulary so you need to define your own or reuse an existing one.
It's an Hypermedia type. I thought it was clear in the title. Apparently not... 😅