5 ms·

I'm with him until he gets to "Hypermedia Controls", which strikes me as needless bureaucracy. The 'link rel = "royalhope.nhs.uk/linkrels/slot/book"' element i

I'm with him until he gets to "Hypermedia Controls", which strikes me as needless bureaucracy. The 'link rel = "royalhope.nhs.uk/linkrels/slot/book"' element isn't really helping anything. Before you can consume that service, you need to know what "royalhope.nhs.uk/linkrels/slot/book" actually means, and if you already know that, then having it listed here in the response justs wastes space. He's disguising a custom verb under a cloak of some sort of 'standardization' which isn't actually part of HTTP or any common web practice. The consumer of this service will need to know what all the verb URIs mean and precisely how to use them anyway, so listing them here doesn't provide any benefit and significantly complicates the communication. In this way, the "Hypermedia Protocol" doesn't demonstrate any edge over old-school XML RPC. Up until that point, I agreed with the article. Simple objects exposed using standard HTTP verbs is the way to go -- but I stop short of supporting random lists of verbs labeled with URIs as just more needless bureaucracy.

scott_s 16y ago
I understood it to be decoupling the what from the how. In this case, it decoupled knowing that you needed to book an appointment from the URI that lets you do that. If I already what what I want to do, but I allow a service to tell me how to do it, me and the service have a looser coupling. If the service decides to change how I accomplish the task, then I should seamlessly adapt.
- stevenwei 16y ago
  But, in practice, how often does a service change an URI only, without changing the input or output parameters (causing you to have to re-factor your client anyway)?
  - drewp 16y ago
    Often merely moving from the dev environment to the release environment changes the URIs. Sure, you could try to minimize the part that changes between environments and teach all your clients to form correct URIs between environments, but it's still coupling. And dev/prod is hardly the only thing people find themselves adjusting in URIs; it was just an example.
  - wahnfrieden 16y ago
    One example, if you move domains, all you'd need to do is redirect the single entry point URL to the new one without having to force clients to change anything and with having to redirect every single API request. You can also allow other sites to implement the same API and clients would only have to select a different entry point. Look at AtomPub for instance.
boucher 16y ago
He states very explicitly that his examples weren't any kind of standard, as one doesn't truly exist at that level. I think the point he was trying to get across, and really what a lot of people who are advocates for REST are trying to accomplish, is that in a fully realized model computers would be able to understand how to talk to each other to get information and update resource states without the need for human intervention. Clearly we are a long way from that goal, but I think it's still something worth talking about.
- DJN 16y ago
  Whilst the notion of "computers talking to each other without human intervention" sounds like a utopian ideal, I think his method is a recipe for disaster. The domain of possible consequences of changing protocols and semantics on the fly is hugely complex. What about testing? Are we advocating that we change live systems without tests? The author writes: "Level 3 introduces discoverability, providing a way of making a protocol more self-documenting." I reply: The same way good design separates presentation, logic and data, it follows that good protocols separate data from documentation.
  - hammerdr 16y ago
    > possible consequences of changing protocols and semantics on the fly is hugely complex Except when you assume that you're reading the semantics from each and every response. It introduces some complexity to how clients need to accept responses. However, once that part is done the changing protocol and semantics should not disrupt the system. And testing? That's not a very difficult component to test. Throw a few different 'schemas' at the HTTP client response module and then feel safe to drop that into your application. I believe you're imagining a system that is more highly coupled to the response schema. This approach is meant to remove that coupling entirely (well, except for a base uri :)) I agree that embedding <link />'s into the response is a violation of a separation of concerns. They should probably be separated in some way (HTTP headers?). However, there are precious few examples of this in the wild and we may see some creative ways to separate these (I just hope we don't go the way of XML to have a different resource to specify schema).
- 16y ago
asmithmd1 16y ago
I agree. If he truly wants to create a system that can be updated only from the server side he needs some sort of human readable description for the control. displayAs = "Book Appointment" for example in this case.
deleted 16y ago
[deleted]
DougWebb 16y ago
The idea is that the client code will search for the link element whose rel attribute is equal to the known value the client is looking for, and then get the uri attribute for the request. In other words, the client knows the name of the uri for the functionality it wants, but it doesn't have to know the uri. This allows the uris to change if needed. It's like using constants instead of literals in your code. If the literal value has to change you only have to change the constant definition, not every place in the code where the value is used.
derefr 16y ago
Look at it this way. If I'm at a REPL, and I have this: o = SomeObjectOfUnknownCapabilities.instance then I can do this: p o.methods ...and see what I can call. The method names give me no guarantee as to what the methods will actually do ("slice" could return a subset of data, or cut a pie), but once I have the verbs, in either case, I can experiment. That's the important bit here—discoverability isn't about knowing what new things do right off the bat, because that's impossible unless there's a finite set of things you can do; discoverability is simply about being told the affordances, so you can manipulate them and observe the results.
Supermighty 16y ago
I want to agree with you, "Hypermedia Controls" seems a bit odd to me, but I don't think it's such a new concept when it comes to REST. This is from Roy Fielding's blog: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... ... all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations.The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.] He's explicate in that a REST system must return options for further action. Links. This is the default behavior of the web, request a page get a page full of links. Martin Fowler is just describing a system that uses a hypermedia implementation other than html. The benefit to this is that you don't need out-of-band information to interact with a new server you run into.

scott_s 16y ago

I understood it to be decoupling the what from the how. In this case, it decoupled knowing that you needed to book an appointment from the URI that lets you do that. If I already what what I want to do, but I allow a service to tell me how to do it, me and the service have a looser coupling. If the service decides to change how I accomplish the task, then I should seamlessly adapt.

stevenwei 16y ago
But, in practice, how often does a service change an URI only, without changing the input or output parameters (causing you to have to re-factor your client anyway)?
- drewp 16y ago
  Often merely moving from the dev environment to the release environment changes the URIs. Sure, you could try to minimize the part that changes between environments and teach all your clients to form correct URIs between environments, but it's still coupling. And dev/prod is hardly the only thing people find themselves adjusting in URIs; it was just an example.
- wahnfrieden 16y ago
  One example, if you move domains, all you'd need to do is redirect the single entry point URL to the new one without having to force clients to change anything and with having to redirect every single API request. You can also allow other sites to implement the same API and clients would only have to select a different entry point. Look at AtomPub for instance.

boucher 16y ago

He states very explicitly that his examples weren't any kind of standard, as one doesn't truly exist at that level. I think the point he was trying to get across, and really what a lot of people who are advocates for REST are trying to accomplish, is that in a fully realized model computers would be able to understand how to talk to each other to get information and update resource states without the need for human intervention. Clearly we are a long way from that goal, but I think it's still something worth talking about.

DJN 16y ago
Whilst the notion of "computers talking to each other without human intervention" sounds like a utopian ideal, I think his method is a recipe for disaster. The domain of possible consequences of changing protocols and semantics on the fly is hugely complex. What about testing? Are we advocating that we change live systems without tests? The author writes: "Level 3 introduces discoverability, providing a way of making a protocol more self-documenting." I reply: The same way good design separates presentation, logic and data, it follows that good protocols separate data from documentation.
- hammerdr 16y ago
  > possible consequences of changing protocols and semantics on the fly is hugely complex Except when you assume that you're reading the semantics from each and every response. It introduces some complexity to how clients need to accept responses. However, once that part is done the changing protocol and semantics should not disrupt the system. And testing? That's not a very difficult component to test. Throw a few different 'schemas' at the HTTP client response module and then feel safe to drop that into your application. I believe you're imagining a system that is more highly coupled to the response schema. This approach is meant to remove that coupling entirely (well, except for a base uri :)) I agree that embedding <link />'s into the response is a violation of a separation of concerns. They should probably be separated in some way (HTTP headers?). However, there are precious few examples of this in the wild and we may see some creative ways to separate these (I just hope we don't go the way of XML to have a different resource to specify schema).
16y ago

asmithmd1 16y ago

I agree. If he truly wants to create a system that can be updated only from the server side he needs some sort of human readable description for the control. displayAs = "Book Appointment" for example in this case.

deleted 16y ago

[deleted]

DougWebb 16y ago

The idea is that the client code will search for the link element whose rel attribute is equal to the known value the client is looking for, and then get the uri attribute for the request. In other words, the client knows the name of the uri for the functionality it wants, but it doesn't have to know the uri. This allows the uris to change if needed. It's like using constants instead of literals in your code. If the literal value has to change you only have to change the constant definition, not every place in the code where the value is used.

derefr 16y ago

Look at it this way. If I'm at a REPL, and I have this: o = SomeObjectOfUnknownCapabilities.instance then I can do this: p o.methods ...and see what I can call. The method names give me no guarantee as to what the methods will actually do ("slice" could return a subset of data, or cut a pie), but once I have the verbs, in either case, I can experiment. That's the important bit here—discoverability isn't about knowing what new things do right off the bat, because that's impossible unless there's a finite set of things you can do; discoverability is simply about being told the affordances, so you can manipulate them and observe the results.

Supermighty 16y ago

I want to agree with you, "Hypermedia Controls" seems a bit odd to me, but I don't think it's such a new concept when it comes to REST. This is from Roy Fielding's blog: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... ... all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations.The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.] He's explicate in that a REST system must return options for further action. Links. This is the default behavior of the web, request a page get a page full of links. Martin Fowler is just describing a system that uses a hypermedia implementation other than html. The benefit to this is that you don't need out-of-band information to interact with a new server you run into.