Select text to annotate, Click play in YouTube to begin
00:00:09
welcome to this session my name is Stefan forgive me to talk about rest I've said that a few times so I gathered up some stuff that I found occurs again
00:00:20
and again and discussions about rest my plan for this session is to start off with a pretty brief introduction but I only do that if some of you think it's worth your time so how many of you have actually been doing rest in practice
00:00:34
building some systems and stuff like that okay who hasn't ever done anything with rest and has only the faintest idea what it might be about okay so yeah so
00:00:48
who considers themselves an expert oh that's a funny question not even raises his hand which is weird okay so well thanks we're going to talk about rest um let's start with his intro and get available with pretty quickly so
00:01:00
this is what rest is it's all actually pretty easy it's a number of things sorry miss mr. messed up my animation yes so what you can see up top that's essentially the
00:01:13
definition of rest all very easy it's a number of constraints and architectural style that's all thanks have a nice day so obviously in this in this dissertation this PhD thesis there's a
00:01:26
lot of stuff there are a lot of definitions there are a lot of things that cross reference each other and actually there is nowhere in this dissertation you can you find a single sentence that says this is what rest
00:01:37
actually is right I think it's a pretty good paper it's a pretty good document it has has excellent value and it has the the great benefit of being the one answer giving the the one answer on any
00:01:51
question you might have everything that refuting the inventor of rest has as answered in this paper is an authoritative answer that's there's no arguing with that unfortunately he doesn't answer everything or at least he doesn't answer
00:02:03
it in an easy-to-access way and many people T wondering whether rest is as ill-defined as other things that we're dealing with for example SOA or
00:02:15
components or object orientation or microservices and it's not actually rest is pretty well defined because it has this definition because it has a set of architectural constraints so what that
00:02:28
means is that you define a set of rules and if something adhere to adheres to those rules then it can claim to be an instance of this particular particular architectural style right so an architectural style is to an
00:02:41
architecture as a design pattern is to an implementation right it's it's it's a bit more abstract it captures certain things about about about how you might want to approach something and if you follow these particular rules then you
00:02:54
can claim to have built an instance of this you don't have to do that and there are as Roy would be the first one to point out disadvantages to some of those things for example stateless communication means that you don't that
00:03:07
you don't gather up sessions stayed on the server side so that has a cost it means you have to either make stuff explicit on the server side it says something stored there or transferred transfer it with each request what you
00:03:19
have choices to make and that's what all this is about so to give you some sort of introduction here to give you some sort of identification I pick one sentence from from the from Roy's PhD
00:03:31
thesis which talks about a number of things so the first thing it talks about is identification of resources identification of resources is something that we see on the web all the time right it's what we're it's what we're
00:03:43
using all the time every time we see a bus going by on the street that has a URI has a URL on its side we use this concept because we can take that URL and put it into our browsers address bar hit enter and get back a page that tells us
00:03:56
something right so identification of resources on the web means users use a URI for everything that you that you think is worth it right everything that you think has has value should have its
00:04:07
own URI so that you can reference it so that you can access it directly one of the great values of this of this rest idea is that we all agree on a way to identify stuff right so we make this
00:04:20
kind of identity concept universal it doesn't matter whether it's my application or your application or Josh's or Ian's whoever has built that stuff if they only use the same concept they all use you arise then we have a unified
00:04:33
idea of how to identify things which means they become targets for links you can link to them if they don't have a URI we can't do that they become something that you can bookmark so do so
00:04:45
that you can go back to it later they become entry points to your application if your application has a single URI it has a single entry point in fact that's the case with many web applications that are built in in big companies many of
00:04:58
the applications I deal with are built this way and that's sad it offers this concept or it sacrifices the idea of identifiability to some some weird idea of programmer
00:05:09
happiness I don't really understand why people who program JSF talk about programmer happiness but some some of those applications built this way lack this simple concept of giving everything that's important its own URI so the
00:05:22
first thing is just that note also that I'm not talking about about web services here right I'm talking about anything that's on the web it doesn't matter whether it's something something that you might call a web service something
00:05:35
that that offers you JSON over HTTP for some programmatic interchange or something that is a UI application that gives you some HTML doesn't matter in fact this distinction was never important to to somebody like royalty to
00:05:48
the people actually came up with these whole ideas it's all just the same thing now once we have those things those identifiable things we have to somehow interact with them the way to interact with them is by means of representations
00:06:01
so they can they can become represented in some data format and that actually gives us some some aspects that your that we're all familiar with as well there is a certain amount of metadata we know something about the stuff that we
00:06:14
exchange with a server there's something like a content type and there's an accept header allowing us to do content negotiation we have a in fact a separation of separation of concerns of certain things we have a separation of
00:06:27
concerns of the actual data that we send the the identity that this data has and the location where it's at so this is these are all separated parts identity
00:06:39
is something that's far more constant in the applications lifecycle in the systems lifecycle than the actual data that's being exchanged if you think about that for a while if you come up with all the things that are worth being identified
00:06:52
in your system like for example your customers and your orders and the steps in approving something or whatever it is that you find a find of being worth of
00:07:04
having having it's on your eye those identities are very very stable the data might change the format might change but what has an identity today will probably have an identity next year as well so if
00:07:17
we separate those things if we make us if we introduce a separation of concerns we can actually have multiple representations at the same time so we have the same thing represented in in various different ways at the same time
00:07:29
or different representations over the course of time so these might actually be if you want to call them that versions although we'll get to that in a moment so if a customer gets five new
00:07:41
attributes that's perfectly fine they get five new attributes but it's still the same customer right still the same entity the same identity that was there before using this concept we reduce
00:07:53
dependency on implementation details we have this URI this thing that identifies something it doesn't matter in which system it resides it doesn't matter whether you move it somewhere as long as you have a URI to it you can connect to
00:08:04
it connecting to something by means of its URI is probably the the most well the most loosely that were the least coupled way to access to connect to something right you connect to something
00:08:18
if you only know once you arrive by means of the assumption that it's going to have something that'll serve a data over HTTP right it's a very weak assumption results manipulations
00:08:30
representations also enables the post processing model it's typically connected to the type of data that you exchange for example if you use HTML as a data format then there is a then there is a certain processing model connected
00:08:42
to that the one you're all familiar with right forums and links and you submit something you get back something you get a redirect whatever it is that's actually HTTP the the format itself defines the way the representations that are sent back and forth between client
00:08:55
and server is a general principle that you can as you can with many things see embodied in HTML but cannot can and should also strive for in your own designs so second thing we have those things and they have
00:09:07
representations the third one is that we have hypermedia as the engine application state I won't make an acronym of that because it's stupid so hypermedia is the at the engine application state essentially means that
00:09:19
once you have all of those things you link them together in a meaningful fashion right they're connected in some way and those connections between things are something that you want to surface in your API or in your system in yours
00:09:31
in the surface of your service service design right so the the primary thing that people people talk about when they when they talk about about connecting UI hypermedia is links right many people
00:09:44
talk about links by the way there are seats left in the front if you don't want to stand in the back so links is the first thing but there are not only links there are also forms so that you can actually build up a new request based on data coming to you from the
00:09:57
server we'll get to that as well there is a certain flow idea here right so we have hypermedia as the engine of application state with the sense that you actually navigate through an application by means of the responses
00:10:09
that you get from the server you don't have a predetermined path that you have hard-coded in your client that goes from one step to the next you have something that is that is done based on the under on the amount of information that you get one of the kind of information that
00:10:21
you get from the server actually I'm repeating myself but if you look at HTML in the browser that's a great example of a restful system now somebody will complain but the browser doesn't do put and delete screw it I don't care
00:10:34
in terms of HTML and hyper media and the responses and the kind of heart the low amount of hard-coded assumptions in the in the browser it allows an excellent example of a very great restful client
00:10:47
finally we get to decide where to put status right we can we can put state in there in the responses and have them have it sent back to us in the next request or we can put the state on the server have it addressed by a URI these
00:11:01
are all aspects of the decisions that I make when I design my hypermedia my media system so three things we have identify things we've give them a URI we exchange representations so we separate
00:11:15
identity in the actual data that represents what's what's identified by this by this thing and then we use hypermedia as a thing to control our flow finally we have self descriptive messages and self descriptive messages
00:11:27
essentially just means that you should be able to make sense of something if you look at the actual message right so this is sort of a manifest against metadata I shouldn't have a
00:11:38
documentation to read to make lots of assumptions unless unless that documentation is standardized and part of an RFC that's fine I'm not supposed to take a look at a message for which I do not
00:11:50
know the protocol or the format and then magically in sort of some sort of AI way make sense of that that's not what this is talking about rather we're talking about using standardized formats wherever
00:12:02
possible using well defied formats where I can actually from the message conclude where I can find more information about what's happening right so again we have the metadata aspect within the message
00:12:16
right so the message itself for example might contain a content type there's a header called content type that says this is the identifier for this content type so that I can go to the Ayana and look up in the content type registry
00:12:27
which RFC defines that thing and then find out what it actually means that I'm looking at right so there's a there's a standardized way of addressing the other so standardization plays a very important role here another aspect is
00:12:40
that you get from this provider independence right they're not I'm not accessing something that is specific to this particular instance of a service or to this particular machine I'm talking to I'm not using Amazon's HTML if I talk
00:12:54
to Amazon to buy a book I'm using the same HTML that I'm using when I talk to Google Rights the same format it's the same thing I'm ideally at least formats are independent of particular entities
00:13:05
that actually use them right um this whole idea of having all of a standardized information all of these headers enables us to produce very very useful intermediaries so we can put a
00:13:17
machine between a client and a server without knowing which climb in which server that's going to be right there's a box there that we'll just take a look at the messages and do something useful with them my favorite example is
00:13:29
always the caching intermediary something like a reverse proxy cache that'll sit somewhere and look at the messages and based on the metadata that tells you something about the about the freshness requirements will
00:13:41
intelligently put this information in memory and serve it to you from there this is all something that you can only do because the message itself is so descriptive in fact if you come from an SOA background and many people have done
00:13:54
s away before they discovered rest which is sort of tragic because it was originally the other way around so many people any people who have discovered rest after sowa find a similarity between the vision
00:14:06
that was in in this in this web services world in terms of so patters right but that's not a coincident it is exactly the same thing in fact one of the people who wrote the soap spec was earlier a
00:14:19
member of the HTTP working group and helped write the HTTP spec of course you can see similarities here and but in contrast to the web services world this one actually took off in a big way so we
00:14:32
have this theoretical definition we have a PhD thesis we have lots of talk about architectural styles and many people really admit that they have never actually managed to reap the thesis but I can tell you it's actually not that hard I'm not a good thesis reader and
00:14:44
not at all but I could I could manage so probably you can as well so who will be who here has read the thesis that's that's impressive that's about five that's that's a better number than I usually get so maybe you should do that
00:14:57
on a rainy Sunday afternoon phrase differently if we really if you really boil it down if we try to distill the essence of all of this then it's nothing more than what we see in the web right we have this web thing that we're
00:15:09
working with all day and the web is exactly that it's lots of things with you arise or URLs if you prefer write lots of things that have a URL and they're all connected by means of hypermedia
00:15:22
so you can link to something directly you can post to something you can share something on Twitter or whatever it is they do on Facebook so you can do that and it's governed by standard formats all right so that your generic client
00:15:36
can actually stand back still today that's the case we can hope it'll stay so for a while we're not all going to be using whatever Facebook's successor to HTML is going to
00:15:47
be called so this is this is sort of the groundwork right we have this we have this idea it's very important to notice this it's not something just for web services it's not the not the thing that is supposed to replace soap right it's a
00:16:01
completely different level they were talking about here we're talking about this abstract architectural thing that has certain constraints and that actually governs actually tells you when you can claim that something is restful
00:16:14
or not now I've been doing this for a while and despite my efforts it has actually become more widespread sorry so it has actually been quite successful
00:16:26
it's all resting these people noticed that there is a lot of value especially opposed to two alternatives that around there but there are some common misconceptions some things that people think and I've listed a few I would love
00:16:39
to get more from you assumptions or misconceptions or things that you strongly believe where I am wrong or where you have seen others a call something risk that you think is not and I left some discussion on that so let me
00:16:50
get quickly through this and we can see how many of those you have run into and how many of those you agree or disagree with so this one is probably my my
00:17:00
favorite one so rest is about pretty you arise right we have the we have a nice restful URL or a rise right nice restful URI and that's just totally it's it's
00:17:15
totally broken this whole concept is totally broken so let's let's take a look at why that is the case I present you some you are eyes right let's take a look at this one who would say that's the restful URI who's who thinks this is
00:17:28
restful okay let me phrase it if you thinks it's not restful that's significant number if you care why not any idea why not the format why twice
00:17:40
format a problem in that URI sounds instructive destructive okay destructive any other thing it's mixing
00:17:52
different entities right there it has a query parameter okay it looks like a command okay anything else good sorry
00:18:05
no identification okay what about this one is this a restful you are I thinks this is a restful you arrived for five who thinks it's not that's a few more so
00:18:19
why do you think it's not a restful URI it has get details it sounds like a verb right anything else query parameter somebody said right so that will reply as well anything else
00:18:38
the customer doesn't have a unique nuke unique ID or URI for customer okay okay so the customer can actually be identified good
00:18:52
what about this one who thinks this is not restful why not it contains a verb again okay anything
00:19:03
else sorry it's repeating what we should do with HTTP verbs household there's a delete in there anything anybody else any other comment on that what if I use
00:19:20
a delete to do to invoke that is it then restful or not deletes the delete command okay okay what about this one who thinks this is a restful URI who
00:19:34
thinks it's not poop stains okay final one what about this one is it restful some people say what why is it restful
00:19:51
it has an ID okay who thinks it's not restful why not sorry I didn't catch that I'm sorry it's good a verb in it
00:20:05
again okay so what if this returns an edit form is it then in restful people you are crazy I don't know why this happens all the time it's really no think about what we just
00:20:18
did I showed this slide this slide write to everyone in this room I showed it to everyone I made a point of saying there is no such thing as a restful URI and the very next second I put up this slide
00:20:31
right and nobody except Ian well that's probably true some people did never never raise their hands and I just assumed they didn't want to spoil my stupid joke right so essentially you can make no assumption whatsoever from the
00:20:44
letters that from the characters that make up a URI you have no idea what these things do I didn't even tell you what verb I use right so maybe if I do a delete on this URI in number 3 that's
00:20:56
exactly what I want that's a particular URI that exposed from the server so that somebody can do a delete on that why would that not be restful why would a query parameter not be restful this it's
00:21:08
just characters right nobody cares about the characters in the URI yet everybody argues about them all the time this happens all the time people decide they want to build something in a restful fashion so they spend all their time
00:21:20
arguing about where the slashes go now that's it that's a good discussion I like discussing pretty you arise and I really really like pretty you arise but it's got nothing to do with rest because if you look at it from a rest
00:21:32
perspective there is no such thing as a restful your eye all the separation into different parts that you can look at it's all true but from a rest perspective this is just one big single thing you shouldn't be worrying about
00:21:45
the characters in the URI because what you should care about is not that it's not the letters and not the characters you should be caring about the context in which they appear right you have something return to you from the server
00:21:57
lesson context that's what you should be parsing or reacting to that's actually what your browser does right at least most of the time your browser unless it's Google's browser talking to Google but that's not something we want to imitate right people don't want
00:22:10
should not be looking at the URI should not be looking at the characters because then I can change this to something like that and it'll still work right that's a hyper media context it's the first litmus test for your REST API whether
00:22:22
you depend on characters on specific characters in your in your you arise for things to work now I'm not talking about a server the servers for a server is perfectly fine to to decompose the URI
00:22:37
to somehow dispatch this to kill how else would it work I'm specifically talking about clients if you ever find yourself within your client connecting things you know using string
00:22:49
concatenation something is really really wrong because you have not applied a hypermedia a counter aspect to the whole thing make any sense okay so next time somebody asks you is this URI restful
00:23:01
just be smug and tell them you you're stupid don't do that it's the risk it's your risky thing so you should be really careful okay so the next one that I see is this one now this a set of you
00:23:14
arrived patterns with get put post to lead and the effects that has I actually I have to admit I advocated something like that for a long long time as the perfect way to do rest I like to give
00:23:27
myself and the benefit of doubt I talked about the hypermedia thing too right I did that but I didn't talk about it as strongly as I today actually these guys Ian and Jim and Savas did it a lot more
00:23:39
strongly in their book because they made hypermedia very very important thing from the very beginning always claimed there's no such thing as a restful api with hydra media now this is much much better than what people did five years
00:23:53
ago because five years ago you could shut down a server using a get hopefully everybody these days understands why that's not a good idea right because the Google crawler assumes that they can do a get because
00:24:06
that's not supposed to anything destructive and if you shut down a server when somebody issues again then it's your fault not theirs right so there's a there's a lot of there's all of two things going on here people actually
00:24:19
build things and that's better but it's still not what you could actually label restful these things look like this who here has an API that looks somewhat like this
00:24:30
so my guess is most of you right in fact most of the people who actually expose an API on the web have something like that even though even the big companies do something like this why what's oh
00:24:43
well what's wrong with this what what would you what would you imagine is wrong with this thing anything version numbers okay I agree anything else
00:24:55
discoverability why lack of discoverability okay it's a good point anything else you see this thing who thinks there's nothing wrong with this it bit it it's fine
00:25:10
I I'm not I'm not insulting I'm sure I'll try not to insult you later I'll do the insulting later on later so that the major problem in my view is we
00:25:22
make the URI is the API right the you arise are now what people will code against right that's the desert description it says this is what the URI looks like this is what their code is going to look like it's going to pluck those things together it's going to
00:25:35
follow those templates and maybe maybe they'll put those templates those URI templates you know with the curly braces into their code so maybe but maybe they won't maybe they'll just use it as a you
00:25:46
know as a as a way to to tell them how to construct their string concatenation code right that's what this is going to do it's it's separate from the actual implementation because it's a separate document this may be in it well if
00:26:01
you're if you work in an enterprise this is in a docx file right in a Word file that you can download from SharePoint if you're if you're on the web it's a PDF right if you're if you're really on the web it's an HTML file which is a great
00:26:15
great thing if you really rest it's part of your app so this documented URI thing is the first first thing the next one is immediately related to to that which is the there are assumptions that now
00:26:27
become effect so for example do I have in this example I have customers and orders right so the orders are a SUP resource under the customer which is from a pretty URI design
00:26:40
standpoint maybe the right thing to do because the slash implies hierarchy am i talking about anything restful here no I'm not just pretty your eyes right so maybe there's some hierarchy you want to express so that's why you put the orders
00:26:51
under the customer but maybe a year from now you want to put the orders into a separate system now everybody will assume that they can take the customer URI and append slash orders to get to
00:27:04
the orders which is bad that is not what should be happening what should be happening is that in some response from the server there's a link to the orders that you follow to do that right so you make it way more dynamic and of course
00:27:16
Josh is right because there are version numbers and you arise and version numbers and you arise just suck right everybody does it which it doesn't make it any less sucky it's just a stupid idea don't do that anybody want to talk
00:27:28
about versioning you're right it's exactly the point the version number is in the URI because the URI is the API right that's part of it so if I change the API obviously the rules for
00:27:44
constructing the URI is changed right now what's the alternative what could we do so let's address this just very briefly because otherwise somebody will ask the first thing what so when we talk about versioning the first thing the
00:27:57
first question we have to ask is what is it that we're talking about what are we versioning here are we versioning the actual data you know is it maybe this version of the customer you know this is the version before George edited the
00:28:10
customer record and this is the one after he edited it that's it that's a version of the data they were talking about maybe it's a it's a confluence document or the version of a file or whatever right if you do that then
00:28:22
that's perfectly fine it's actually the one case where I don't even object to having a version number in the URI because that's then just part of the pretty you are writing again maybe if you want to express I don't care just do that if you want if it makes you happy
00:28:33
just do it but that's the only occasion where you should be putting your version number in the URI because it identifies the data that this URI points to right if you make every version number a separate thing with its you a ride and maybe you want to relate
00:28:46
them somehow so that people can see that immediately the same is true logically by deduction for documentation because documentation is just data as well right that's one of the nice things in a restful scenario everything that you can
00:28:58
express as a resource is now part of the same same set of concepts so every documentation page that you have can be its own resource that you can link to from the other pieces sent back and
00:29:10
forth as you know formats if you want to you I well I'm not a fan version you're formats I don't think version uniform ATS means much but if you're happy to do that then just call your media types if you if you
00:29:23
dare to invent your own give them a version number suffix or something I again I think that if text slash HTML got by for for 20 years then you can probably to but if you if his some
00:29:35
reason don't want to do that and just put a put a version number in there the one thing we I really have a problem is an API because I don't even know what that is if I'm if I'm a if I'm a big company it offers lots of stuff to my to
00:29:48
my clients what's the what's the boundary of my API is it everything I do is it the Google API how often is the Google API going to change its version
00:30:00
right if they introduce a new service is that is it a compatible change is something no it's not it isn't changing anything specifically it's not it's not changing the identity of anything how stupid would that be if it did right
00:30:13
there's identity suppose the most long-living thing that you have their rights it should be stable over years cool you arise don't change and all that right there written 15 years ago so those things should be stable putting a
00:30:26
version number in the URI means you have to change the you are eyes all the time with no reason at all it's not a good idea right so what I recommend is actually use different media types not provisioning use them for different
00:30:38
things kind of obvious right use the version number in the URI if you want to do version the thing itself right you know that particular document I'm fine with that and build new resources if you have new aspects it's kind of a standard
00:30:51
versioning strategy right you have to have some new thing that you want to say about this stuff so we'll build that new thing linked it to the other one that's what the web is really great at right new things that are connected to existing
00:31:04
things which means of course that you have to reserve space for links right so you have to be able to within that existing representation have some place where you can put links to additional stuff right and that has to be designed
00:31:17
in to your formats from the very beginning that's a very important thing and to keep people happy because some architect is going to tell you you have to have versions version your Doc's works amazingly well right just make a
00:31:31
document that says this is the documentation of our API and give it version 2.1 that's cool now everybody has version which is just just the version of that document and you can apply any versioning logic that
00:31:43
you like it doesn't have anything to do it does not belong at all into your actual exchanges it doesn't have anything to do with your identities doesn't have anything to do with your formats it's just a document that you version right so yeah I'm actually
00:31:55
telling you should not be versioning and I'm really happy that Josh said the same thing this morning so apparently some people can do they're not kind of happy with it any questions regarding that any
00:32:06
disagreements here come on people you have to disagree somebody has to do that yes please so you were saying there is a speck that puts the verse number into the HTTP
00:32:27
header I'm not aware well of course you can sure you can invent custom headers as much as you like with the same pro's and con's that that apply if you invent your own HTTP verbs right you can do
00:32:40
that you attach semantics to something that is not standardized now that actually maybe find sort of ties back to the self descriptiveness constraint right so maybe self descriptive for you means it's well defined within your
00:32:53
company are well defined within your organization and the peers that interact with it that's fine it's like a it's like a local standard that you have established if everybody does that and that's fine you won't find any standard
00:33:06
infrastructure that will do anything meaningful with that you might you are at risk that somebody will drop that header for example because some proxy will filter out all the headers doesn't know so there are some risks but maybe you derive benefit from it what I object
00:33:18
to is that you actually have to do that because what I think is the that is a general rule right so this is actually this particular thing here right do you know this one Pascal's law it's a kind
00:33:31
of the robustness principle things that make stuff stuff simple right which essentially means we should all should be nice to each other so if everybody does that right if everybody is is literal when they accept something and Ridgid when they send something than if
00:33:44
you bill connect stuff bla bla bla you'll build up with a more resilient network of things right that's that's kind of the idea every time you you make your very very strict about the stuff that you accept on the incoming side you
00:33:56
introduce a potential breakage that shouldn't be there because you're really just being an ass right you're just looking at that and saying well sure I could I could do it but I won't it doesn't follow the spec I refuse to
00:34:10
process this sir it doesn't sound you know that doesn't sound like something that you actually want to do in a system that's supposed to work as opposed to one that's supposed to satisfy some architectural rule so but that's just my just just my view of things right so
00:34:24
there are some rules that actually say what you should and shouldn't be doing to enable this right to in label this this this kind of communication you're kind of should actually say a receiving side on
00:34:36
the left should support unknown links ignore unknown content that's a general principle right you don't fall apart if somebody sends you a field that you didn't that you didn't expect if you're not using it so what just pass it along
00:34:48
or ignore it but don't just complain about right of course you shouldn't be just breaking you arised records although I have seen people do that as part of their of their bill right they occasionally they break all the URI structures on the server to see which
00:35:02
clients fail which is kind of a funny approach that you can only do in a in a scenario a weather where you have power over your clients don't do that if you're a web api and just it's not a good way so back from from versioning
00:35:17
right if we have this idea about hyper media you remember this table that I had with these things what's what's a possible step and one thing that you can do if you have a REST API and want to make it more hyper media aware is
00:35:29
introduce something like call a service document which is a stone term right so service document is like like a home page right this is a home page for my order management service it has links to
00:35:41
reasonable things that you might want to access from there and of course you could encode that in XML or another machine readable format and then essentially your client does the same
00:35:53
thing that you had a user would do if you looked at that page right here the client is no longer hard-coded against the URI it's hard-coded against the value of this rel thing right so if you look for
00:36:04
example at the cancelled or the fulfilled link relation then this one says well here if you if you want to take a look at the orders that are already done then you follow this link relation if I change the URI to to point
00:36:18
to some archive system nobody cares right because it's just one level of indirection it's not magic it's not AI or anything it's just simple simple adding a one level of indirection which might be exactly what you want to do if
00:36:30
you have a device like this right that's that that's a pain a pain to update right it really sucks to out have it for that you have to update an application one of these then you can actually do it this way and this thing becomes
00:36:42
magically aware of new stuff or new look the things that's that's you pay for it with this extra indirection which you can alleviate a bit by caching but you can benefit because you now have this extra level right pretty obvious and of
00:36:55
course XML is totally uncool so I put it in the JSON very in this one there are some standards covering this right the Cenacle json whole which is a draft thing but it's by mark nottingham so it'll be a standard soon and it's
00:37:08
actually a somewhat standardized version of that so that's the first set a service document still is something that is a separate thing from your actual from your actual resource right it's
00:37:20
still it's somewhat meta data like but it's at least in your replication write because I get it from the application the idea here being that my client needs a single URI you give it one URI and that's it from there on it can just
00:37:33
discover everything else solving that discoverability problem right now that's that's a that's a lot better than having it in a Word or PDF document because now you're putting that into the actual runtime the server when it starts up
00:37:46
will start serving the service document with the right links maybe even the right capabilities but obviously you have resources in the first place right so if you have resources why not add links to them from the very beginning
00:37:58
right so if I if I do something if I get an order I can get back in order and that order can have the links that point me to other things that should have the links that point me to other interesting
00:38:08
stuff right so the syntax really doesn't matter right I used something with it with an array here that's that's a good thing if you're programming Java or have people who do that and this one is a
00:38:22
little bit better if you have a modern ammok language it doesn't really matter they've the important point is that you have a place where you can put in links and that you leave in the placeholder for for way where to which put more of them right so that you can evolve this
00:38:34
thing over the course of time and add more interesting stuff to so that's the second thing the first one is it's after document the second one is we add it to the resources the third one is to actually use it for its original purpose which is to drive the interaction to
00:38:47
give the clients opportunities to choose from right so if I have some sort of state machine some flow that's encoded in my server right certain things in the lifecycle this
00:38:58
of an order natal it went to move from which stay - which next stay then then you can express those possible transitions in the hypermedia response so when the server returns an answer to the client that answer will include only
00:39:12
the links that make sense and the client can then only do that because it can only follow those things make any sense right so we sort of control the flow of a client by means of the responses that we returned from the server again it's
00:39:25
just like a browser-based HTML app which is no coincidence because that's just the web right this whole rest thing is not a services thing it's the architecture of the web so again does
00:39:38
this make the client super smart is it now is it now intelligent is it now a human of course not that's not the goal right nobody nobody in this rest space not in the rest of this may be in the same web space but nobody the rest space
00:39:50
actually believes in two systems that become magically intelligent this just means you're not depending on a specific URI you're depending on something that redirects you to that you arrived right that's the only that's really and that
00:40:03
gives you certain certain flexibility here now that's a nice thing but it's still not not the complete misconception because many people do that right but they still think this right hypermedia
00:40:15
is responses with links right so that's all I talked about it all makes sense I don't regret any of it but it's not the whole story right because links is just one part of hypermedia links are really a cool thing it's a
00:40:28
very cool thing and if you have a REST API that uses links to control the client to make the client more dynamic then you've built something pretty neat but you can go further than that the next thing you can do is you can
00:40:41
actually take a look at at more interesting Hydra media controls so the first rule that we talked about is you don't want to have clients build your eyes using string concatenation right that's why we moved from the descriptive
00:40:53
API in that HTML document to something that's contained in the responses that you returned from the server right but the problem is you cannot always enumerate all the possible you arise how would you do that if it's if it can be
00:41:06
one of 20 million customers how are you going to make a return a list if that doesn't make any sense right so you have to somehow give the client a way to come up with the next request with the including the URI you
00:41:19
know all the stuff that they need to have for the next request with some sort of recipe right which is perfectly fine as well so you can provide a recipe to the client it's also hypermedia actually you're doing that all the time with this
00:41:31
example right this is somewhat similar to what the Google homepage looks like right it has a bit more stuff in it but essentially it's what it used to look like what it should look like but it doesn't write it has just a search box
00:41:42
and that search box allows you to enter a query and from a rest perspective you can view this as a URI construction form right you return this from the server to
00:41:54
the client and now the client will enter a query and when they hit submit because it's a get form a new URI will be built it actually you the way how it's built is actually in the HTML spec not the URI
00:42:06
spec or the HTTP spec the HTML spec tells you how a form is turned into a URI when you have a get form so what's built is a new query and that query has what they use here query equals
00:42:19
something with the with the text that you have put into the search view so you provide the client with a recipe for constructing any number of useful you arise and you can do the same thing using a machine readable format it's not
00:42:31
as if HTML weren't machine readable the people don't want to use that so let's just use JSON here and I have a URI template which is by now also a standard and that actually tells you is the exact same thing right it gives you you Orion
00:42:44
it looks like hard coding but you're not hard coding then the characters in the URI you are just saying that you want to you expect to find a query parameter in there once you have a query parameter
00:42:56
you can you can put your your query into that slot and then make a new URL right so that's what you actually depend on and you can do it even you can do even more than that which is give the client
00:43:08
a form that maybe contains some default data right this is like a this is like an HTML form that which is not showing you could have some hidden fields right it's a it's a form actually I'm telling the client how to build the next request
00:43:21
the next post request right it's the hypermedia control and emit this particular case tells the client well if you want to post something to me this is the this is the format that I expect with some values
00:43:33
with some type information right it's all dynamic it's all at runtime you have the information that this is a text field and this is with new html5 controls this is a an email field is a date field and then you can filled it in
00:43:46
and send it to the server which essentially means that you can tell the client to send you a request that the client didn't know how to build when it was built right so you dynamically extend the clients capabilities of sending a
00:43:59
request you can do the same thing with JSON as well right you return something to the client for Matt doesn't matter you return something to the client and the client then is able to use that to build the next request which is a very very powerful mechanism to build stuff
00:44:13
like that okay any questions regarding that so the question is how much information can eyes can have sent to the client right can I let them know what exactly I expect here not in HTML
00:44:26
not yet not right now it's better it's becoming better over time all the time and there are certain ways you can do that with your own more or less proprietary format so you could have you could have something like JSON and link that to a JSON schema use something like
00:44:39
JSON oldie lots of things that allow you to do some of that none of them which allows you to do that in a perfect fashion right so okay so form includes
00:44:52
the E and C time of course you're limited whether you're depending on whether you expect this to work in the browser which that means it's a fixed set or whether you're willing to extend that to something else that you mean yourself that's a good point yes we have more more ways to say how the how the
00:45:04
actual information should be encoded when it's sent from the coin to the server anything else so let me leave you with a final one which is something that I think not many
00:45:19
people including myself do so most of the time we think about rest we're talking about services which is this is wrong that's a different kind of discussion I'm not talking about the way
00:45:33
we could build web UIs unless you're willing to spend extra time some time later I'll talk to you for hours that's all I'm talking about what I'm talking about is even when we're talking about machine to machine interaction we typically have this view of building a
00:45:45
service interface right we're building an interface to some capability right and and somehow that's not really what we should be doing right we are we're obviously not doing that that would be you know some point to point integration
00:45:57
kind of thing but we believe we're doing this we believe we're building an API to a server that will be used by many clients and we can do that in ways that are more or less restful right but what we really
00:46:10
should be doing if we really want to do things by the book and get the full seal of approval of the rest high church something then we should be building hyper media types that are independent of a particular server but we shouldn't
00:46:23
be building something like a Twitter API should be doing that we shouldn't be building a confluence or a JIRA API we should be building a tracker hyper media format because that tracker hyper media
00:46:36
format would enable me to connect any client that knows the hypermedia format to any server that supports that right in fact it would allow me to connect any client to any number of servers that support that simultaneously think about
00:46:49
what your browser actually is your browser is a client that'll talk to a lot of machines at the same time right as it's almost magic it's almost as if you could have a client that could post your status to both Twitter and Facebook
00:47:03
imagine how crazy innovative that would be we there are obviously ideas obviously reasons why neither Twitter or Facebook wants you to to have that but that doesn't mean that it's not technically the right thing and maybe we
00:47:15
should be building stuff that way maybe we should be designing your own fancy hyper media formats except that's a that's really a lot of work it's really hard to do so maybe we should just use some right this is one of those things
00:47:27
application was at some XML that's actually a standardized format there's a there's a publishing protocol as a syndication format that you can use to build stuff or we could use something like open search or we could use one of
00:47:40
those upcoming new fancy things like collection plus JSON or helpless Jason this frantic searching is really fun helpless JSON or siren plus days on lots of existing formats that you could use
00:47:53
to do that or that's the final thought you could just go with text in HTML but I mean that's a very very widespread format why not use that for a machine to machine communication right that would be a really nice aspect because after
00:48:06
all if you look at this why is this completely acceptable and this not there's really no reason why one kind of XML II thing is okay and the other one isn't so you know concluding with the
00:48:19
benefits of using HTML is you have a media format you get this of ubiquity in well-known supported hyper media controls a pretty good standard client lots of programming tools and essentially as Ian told me this this
00:48:31
noon UI is a nice side effect right your API magically becomes usable from a browser if it just uses HTML as its format but we all know that's crazy talk because you would never do that right you would never use HTML just wait a
00:48:43
year it's going to it's sounding just as crazy as wrested 10 years ago and maybe it's going to be the thing of the future that's all I have right now as well so the comment was none of my examples did
00:48:55
I talk about how these links should be accessed right I didn't ever I did not say a user get here in the hyper media format somewhere you could either get a riposte you except in the HTML example in the HTML example I actually had a
00:49:07
form that either had a get or post in it right so there are two ways you can do that either you hard-coded in your in your format's description so if you invent the format then it's your it could be your choice like HTML does with
00:49:19
the IMG tag to say you have a tag as SRC equals something and you're only ever supposed to do a get and that's what it says in respect of your hyper media format or you could make it explicit like Adam does or like HTML s with a
00:49:32
form element and just have a type or action or method attribute that tells the climb to do that the question is how much does that actually give that's why I tend to not put it in because I just assumed the client to be
00:49:44
not as smart to do that at runtime I assumed that the client is smart enough to determine to have the the URI determined at runtime I don't think it has much benefit to provided that flexibility but maybe I'm
00:49:56
wrong it just very much depends on your use case it would be perfectly fine to include that method as well yeah forms are away of programming I will fully agree with that yes so it depends
00:50:10
the browser obviously is a very very dynamic very generic thing the browser doesn't know that you're ordering a book and if you're building a client at that level of generosity is that a work at
00:50:21
that level of being generic right then then it makes perfect sense to have more information in the hydro media controls the less generic the most specific your client becomes the the fewer information
00:50:34
items the fewer aspects of that you need to specify in the hypermedia format so there are many ways to specify the actions that you can do with the document one of the most common things is to include the link relations and have those signify that to the coin so
00:50:47
if I have a document that I can edit and there's a link relation that allows me to edit it that might actually be a good example for not having to specify whether it's a get or put so if I glue the link link rel equals edit that in my
00:51:01
documentation I would say whenever you find that link you can do it get to become an edit form or you can just put the new content then that will be the semantics of this particular type of link you know and I could see that this
00:51:13
is a semantic because the Edit link relation would be documented but in fact it is documented exactly that way and you could you could just you could just use that excellent question do I use do I know any examples of widely used
00:51:25
public API is that fully follow this model no there are some things like there's a new Amazon API I forgot for which purpose it was that uses hell and just some hypermedia aspects there is a the github pull request API that does
00:51:37
some of that but most of the most of those who do really major things don't have much hypermedia I think Facebook has some but another Facebook user so I wouldn't know sorry timbre to the cloud
00:51:49
API for Sun right but that's Sun and for at least we don't have much of that left again but I'm sort of optimistic about the whole thing if it has value I believe it has then it'll it'll appear
00:52:02
in more and more public KPIs unless they have a reason that's not technical but rather you know walled garden like to not enable that type of stuff so thanks a lot for your attention I'm around if you want to ask questions have fun at the conference
00:52:22
you
End of transcript