Oktane17: Designing Beautiful REST + JSON APIs

it is always my great pleasure pleasure to introduce les who I have worked with for many years this is a very special presentation so I'm excited that you're all here and I'm kind of getting goosebumps over 750,000 people have seen les give this presentation rest JSON API design is one of the most complicated things in modern web development and this is I think the best presentation on it so I'm very excited to introduce les Hazelwood who is the former co-founder and CTO of storm paths and now a chief architect a doctor thanks clear thank you can you guys hear me okay is the volume good okay so we're here to just talk about building rest JSON API is specifically your API is that you're building and delivering to your customers or your partners this isn't really going to be a talk about octave zone API it's about how you can build API is great API sand how to make them beautiful so that your customers love them so why are we you're talking about api's I'm Alex's entire presentation if you were here to see that a second ago was all about connectivity and enabling support for your developers and your customers and your partners and and how do you scale out your products and make them easier to consume and use across different you know markets and heterogeneous customers so that's really what ap eyes are all about it's about connectivity but why are we here talking about rest specifically so rest was invented by dr. Roy fielding as an as a PhD thesis for his computer science thesis and he specifically lists out these six points of why restau as a paradigm is very valuable and we don't have really have a whole lot of time to go into each individual point but I really recommend that you check out his thesis he goes into visa at length but all of these really bundle up to ubiquity how do you get massive internet scale adoption that people across industries markets verticals can all communicate with each other at massive scale that's what rest is all about but why are we you're talking about JSON this is a rest Plus JSON specific presentation in the answer is that JSON is pretty much everywhere regardless of programming language it supported pretty much everywhere it's simple it's easy to read for humans so this is sort of a the lingua franca of the modern web so if we're here talking about the modern web and JSON and in kind of HTTP this vol must be easy right these technologies JSON and HTTP have been around for twenty thirty years or more so this all must be very simple we've nailed it right we've we got these technologies down but the answer is that it's not really easy it's it's really really hard actually if you're a provider or of a REST API you're building a REST API and you're presenting it and the reason why there is no specification for rest it is an architectural set of guidelines or principles or a philosophy from Fielding's thesis but it's not codified into a set of steps you know do one two three and then section a and you know all these other rules and stuff it's not codified so we're left to interpret his specification and different people interpret things differently however rest can be easy if you follow a set of common guidelines and that's we're really here today to talk about the fundamentals of rest and what those common guidelines are and what they should be there is a huge amount of technical data in questions I'm sure you guys would have on on some of the minutiae and intricacies of rest and unfortunately we don't have a lot of time to talk about that today but I will be available after this talk hosting a birds of a feather luncheon or at the one of the lunch table so feel free to come talk and geek out about that kind of stuff as well as as Claire said in the developer lounge from 1:30 to 2:30 so in the context of rest a lot of times you'll hear this term hey Deus hypermedia as the engine of application state this is a huge mouthful and it's a terrible acronym but what what this really is trying to represent is that everything in a REST API should be in the documents exchange between client and server and there should be nothing else other than what's in the document that explains everything so if you think of a web browser accessing an HTML document everything the browser needs in order to render the page in order to trigger behavior in order to jump from one page to the next is all codified in that HTML document right so that our HTML document is fully restful because the browser or a person interacting with the browser doesn't need to go to some other website or read documentation to figure out what to do with that HTML document so when you hear hey Dios just think everything is contained within the document everything that that's necessary is in the document and what this really boils down to if you if you kind of dig into this a little further is it all boils down to two things links and state transitions meaning how do I get how do i link from one document to another right that is the huge power of the web that you can link from a document from Google to Stack Overflow to your company's website the power of the web is all about linking how do I get from one location to another state transitions is not how do I just get from one location to another it's how do I send data from one location to another so I'm not just getting a resource or I'm not just getting a new document I'm able to send data to a separate location from one server to another from one website to another so hey Dios boils down to links and state transitions in fact Fielding's thesis if you if you've heard talk or you've seen some of his blog articles everything in rest boils down to these two concepts but a lot of people misinterpret Fielding's thesis and so he's actually coming out with a blog article it's the URL at the top in the this presentation will be online so you can check it out later where he clarifies some things that are kind of shocking especially if maybe like me you come from a typesafe programming language background where things are concretely defined and statically typed and but fielding specifically says well I'll get in the typing in a second but for one of the first things is this communication protocol independent so you don't want to couple yourself to the communications protocol so if I have a restful api I should be able to work whether I'm using HTTP is the protocol or if I'm using raw TCP sockets right and I should be able to take my restful document and send it over TCP or HTTP and so if you find yourself building a REST API and you're hard coding or coupling yourself to HTTP headers and status codes you might not be as restful as you think you are because if you try to translate it to a different protocol well it would break and so you violating one of Fielding's principles they're also a media-type centric meaning it's all about the documents and what's in the documents and the type of document how to parse it is codified by an internet media type or mime types so rest is all about media types and how you parse documents there's also no fixed names or hierarchies this is really hard for people to understand and in in fairness and in truth it took me a couple years to wrap my head around this I mean if I go to a particular URL in a REST API that says I don't know slash user slash 1-2-3 as a human I always expect every time I interact with that URL but I'm going to get a user resource back rest is not about that rest is I have to go hit that URL get the data back I don't have to parse it to see if I can make sense of it it could be a user today it could be a car tomorrow all right sounds weird as humans we make sense of URLs but in reality URLs and naming and hierarchies like hierarchical URLs with namespaces mean absolutely nothing with rest and so if you couple yourself to this notion that things have to be typed according to the URLs you're actually fundamentally violating rest principles um and to that end everything in wrath should be dynamically typed meaning I can't interact with a resource and inspect them get a user back every single time I have to parse the document and everything in it before I can say yes this is the what I understand is a resource for a user or not so there's no static typings in rest you can't always hit a URL and expect to get the same thing back every time and if you do or if you code your clients to just blindly access properties or fields then you're violating rest that's not restful and and most importantly and I'll just reiterate again is 0 out of bed knowledge meaning everything that should be necessary for a client a server to work with each other is 100% contained in the documents exchanged between the servers not necessarily they should be headers not in some other mechanism everything's in the document which means you shouldn't have to go read documentation to figure out how a REST API works if you're reading Doc's it means that the information is not in the doc that's being exchanged really difficult to to address and kind of understand but again happy to talk about these things after the presentation so if fielding comes up with all these clarifications on his spec how do we how do we meet these requirements so we really want to break things down to some some fundamentals um rest is primarily given that it's an acronym representational state transfer state often translates to nouns and nouns or resources are the important thing of what's being transferred there's not verbs represented here like get a user delete a user that kind of thing it's really just user or account or company or organization they're all about the nouns and they should be coarse-grained not fine-grain meaning everything that's relevant for that particular resource should be in the resource you shouldn't necessarily have to jump to five or ten different links or other documents to get everything you need about that one particular resource and that's important because the more information you have in the resource of the document for that particular resource the more clients can self program in and satisfy requirements that maybe you never thought existed so instead of you creating links to all these other things around to say for example a user object if you have all the data in there the user can or the client can consume that data and do things with it that you maybe never envisioned and that helps with Fielding's support for ubiquity or large-scale adoption so to illustrate what I mean by nouns versus verbs what if I had some you are eyes in an application that I'm building like this get user I want to create an application resource maybe I'm going to update a particular group and it's data maybe I want to verify a user's email address this looks fairly innocuous not too bad just for URLs but the reality is that when you couple verbs with nouns in your app this quickly explodes right so you're going to get a ton of URLs in your app that look like this you're going to support them all indefinitely and it's gonna be a huge pain in the button if you've ever done some like soap or RPC programming in the 90s or the early 2000s this smell like bad RPC don't do this this is a bad betting if thy pattern it's gonna cause a lot of pain so if we can't or shouldn't do these things what's the answer well we want to keep it really simple and to do that you can kind of categorize or breakdown resources into two particular types collections resore collection resource meaning a collection of things in an instance resource meaning in one individual thing now conventionally collection resources on the web are typically named in the plural not the singular because it always its self-documenting to a human at least that you're potentially interacting with more than one thing so it's not application it's applications it's not user it's users and we recommend that you stick to this kind of convention it just makes things a lot easier to read and understand and so if this is a collection an instance typically hangs off of a collection it's an easy way to reference that particular resource within the particular namespace now again namespaces don't matter this could just be junk gobbledygook right as far as clients and servers and the rest of paradigm are concerned but this makes it easier for humans to understand what's going on so it's it's a nice benefit so these are nouns and how to get access or interact with these nouns these resources well what about behavior and if you're using HTTP as a protocol the answer is HTTP he already has behavior built into the spec in the form of HTTP methods and so you can do a get put post elite had options you've probably seen these before but one thing that's kind of confusing at times is that a lot of times people think get put post and delete have one-to-one correlations with create read update delete you know we all heard this crud term for database storage and stuff and everyone not everyone but a lot of people think that post get put in delete of HTTP will always have a one-to-one correlation with crud and this is actually not the case this is where HTTP the the specification actually allows you to to do multiple things sometimes however as you might expect get is really a read it is one-to-one correlation delete is really delete I'm trying to delete something on the server head is a metadata operation I just want to get some information back but I don't actually want the resource options as you know HTTP communication options you know pre-flight pre-flight requests for Korres and things like that again these are all HTTP specific concepts they give you some niceties on top of restful documents but put and posts are not so obvious they can both be used for create and update so here's how you can use put for create if the identifier of the resource meaning the fully qualified or canonical URL of that resource is already known to the client before they submit the request so if you allow your clients to create their own identifier for URLs then you can use put for creation in this case where you know somebody's creating an application and they've just generated their own ID for their own app and so they want to save it under that identifier this isn't too common but it is totally plausible or possible with put you can also use put for update though so in a full replacement or rather in a replacement operation I can put to that same URL same existing ID and I and I have two properties in this case name and description but the implication here kind of the interesting bit about put this has to be a full replacement operation same with create you have to specify a hundred percent of the data for the resource you can't use partial updates or partial creations and the reason for this is that put is I'd an item potent it's mandated by the ACD spec this is not even a resting it's an HTTP thing that every put request has to be item potent meaning you can send the same request 110 or a hundred times and the state of the resource after each one of those requests is going to be identical after that's done so if you send in one property on request one and a separate property on request three and then the the you know that first property is sent in on request 15 the state of that resource going to be different across those requests that violates the HTTP mandate for item potency so what has to be everything the whole resource so I'm going to send data in on a put the entire resource in its full representation has to go so just be careful with that if you use put post can also be used as create as well typically it's put down on or rather put is or sorry post is sent to a resource may be a collection resource that's the most common thing and in this case I'm just sending you know a name property and the post response sends back to HTTP headers location header and a201 created so this is really important for HTTP because 201 means not only was a request successful but it was successful and I created something as a result and you have to set the location header to tell the client hey this is where this thing that we just created it now resides here you can go interact with it further if you want to and this this is really important because if you look in the original request the client has no idea what where the canonical location is it doesn't know what the identifier is so you have to set a location header and make sure it's 201 not 200 posts can also be used as update so in this case I'm sending in a new name you know I just want to change the name field on that particular application resource and in this case all you need to do is return 200 okay because the client array already knows the location right there he knows the URI and it 201 is not necessary because you didn't create anything you're just you know changing the state of something so 200 okay is is totally acceptable but as you notice in these examples we're only sending in one property or just partial properties and the reason why that's legal is post is not idempotent it's the only HTTP method in the spec that doesn't guarantee idempotence and that's really important to understand basically and in the ACP spec is very vague on this it basically says it's a server processing directive no and that's basically the extent of what they say which means you can do whatever the heck you want you can mutate the state you can have side effects and change State elsewhere you can do whatever you want during a post so partial partial data or partial submissions totally fine so we've talked about nouns and verbs the other part is just very briefly a review of media types and a media type and this took me a little while to wrap my head around earlier in my career but a media type is a format specification and the set of parsing rules associated with it how do I read the document and make sense of certain fields media types are not schemas though right it's not saying a user resource has this property in this property a media type is more about here's a document and I can read properties right it tells you how to parse the information not the mandatory structure of that information if that makes sense so keep that in mind and clients and servers negotiate documents via via an HTP with the accept header and the content type header so a client will set the accept header to say hey here's all the media types that I support that I know how to parse and the server and a reply or a response will set the content type header that says ok you've told me what you supported well the content types going to reflect what I'm actually sending back as a server to the client so that's called content type negotiation between clients and servers and the content type is most of them are standardized but you can also have subtypes and so if I have application sliced JSON which probably most everyone here has seen you can actually have further specifications on top of JSON by using this prefix notation less ion plus JSON or you know and you can have different JSON specific specs based on this this plus notation and we're will be talking about ion in a second but this is just an example of a media type that's not just JSON but it's JSON plus some additional rules or some structure so ok let's talk about design you guys are really curious about design and jumping into what an API could look like how do we do hey Tio's cleanly in JSON there are no formal official final specs but there are a set of competing specifications on the internet and IETF and the w3c and I'm going to talk to you today about one called ion ioin in in all fairness and just being forward I'm the spec lead for this particular initiative but we have a whole set of people that are participating in this effort from different companies different corporations so it's not just an octal ed thing it's a it's a cross company led thing but we think ion addresses some HTTP or restful concepts and JSON that others maybe don't address too well so what does ion look like you know how would you use it in an API so everything in ion is just JSON right it's plus JSON so that means that normal objects are parsed as normal objects there's nothing special no surprises here so this is just a simple object that represents maybe a person first name last name birthdate ion also introduced this notion of a value object so it'll have an object with a value property and that's the only thing that's required to have a value object now why is a value object relevant or valuable in JSON why don't I just have just properties well the answer here's an example so let's say I have a greeting field or member and in this case the value is all R which most of us will probably recognize as a Spanish national language word but a machine has no idea what that means all right so my machine doesn't know that this is Spanish it doesn't know if it's English or anything it just knows it hey here's a value to this property well if you replace this with the concept of a value object so now I have greeting that's assigned to a JSON object with a value property it allows me to add additional metadata associated with that value so in this case the values still owe ah but now I have a lang parameter or member called es to represent it it's a Spanish natural language worth so the point of the value object is not be not only do you just have a value but you have all this this space for extra metadata to prevent or provide relevance for clients and in humans too they find value in this so that was a single kind of resource what about collections it might you might just say okay well I have a value field let me just stick an array in there um this is kind of a naive implementation in that there's some challenges or difficulties with this and so ion doesn't represent collections this way it actually wraps it as a value object right so there's an object with a value property and the reason why is again you can add metadata so everything that's in the value array maybe there's metadata that's relevant to each element in the Ray and you don't want to repeat it on every single element in the array or maybe there's things like length or max size or things like that that are only relevant to the collection itself not each independent element in the collection and so ion collections are our value objects that are wrapped or rather a value field that's wrapped in an object and we can take this construct and start addressing things like linking and state transitions right the things that fielding says it's really important for rest api's so if you remember or rather HR FS in HTML pages HR F for the anchor distributed hypermedia spearmint this is like one of the most important things that fielding says and it all boils down to links canonical URLs and state transitions it's important to know that HR FS or URLs they have IDs in them but IDs any URL are completely irrelevant to a client all it needs is a URL to go access and that's the only thing that's necessary now as humans we embed IDs in URLs for our own cognitive ability or understanding but clients don't need this so IDs exist but really the the ID of the web is a URL that's the thing that canonically identifies any particular resource and it's critical for linking as we'll see so how do we do it XML has it in the form of the excellent specification JSON doesn't have it yet now there's some competing standards io is one of which hal is another and we'll talk about some of these in a little bit so how do we do this how do we make it simple and clean and JSON well i Indust having a simple HRF property so it's an object with an HR field with a fully qualified you all right what doesn't have to be fully qualified but it's just a URI that the client can negotiate and so if you have a link like this it's very simple it's pretty easy to understand if you've ever done HTML this is totally natural and intuitive so if I can use this link how do I link between resources so here's an example I'm going to get a particular user resource and a user in this example has a given name and a surname but how do I link from that users you know from that user resource to the company maybe their employer and so the answer is you just use that same ion link concept right well I have a company and that's referencing this object with an HR field so this is pretty obvious right this is clearly a link as is recognized by us if the media type parser recognizes it a link it can't reverse it and go to that resource what about collections oh this is a single resource how do I link to a different collection and that's not really any different so let's say a user and they have a collection of groups that they're a member of you just link to it in the same way it's still an HRF there's no difference however this isn't quite enough information to tell a client exactly what's going on here and so we already have this notion of linked relations to finding the X link specification like what is the purpose of the link why does it exist and so we just continue that here anion as well so we have a rel link relation right and this is no different than if you've looked at the HTML anchors right they have a href arielle some value same exact thing just in JSON notation so one of the design considerations for ion is to be incredibly intuitive and easy on a chain and also to support transliteration between HTML and json if that's an if that's a need sometimes that's valuable for legacy products or existing documents that need to be translated to JSON for modern clients like angular react so the client now knows oh not only is this a link but it's a link to a collection of things and then of course you can add more metadata in there to give to you know what's the media type what what media types are supported so I know I can maybe negotiate and get XML if I wanted to or JSON we also recommend this notion of a self link for every every resource that's on the web so it's a link like any other it's nothing special but one of the cool things about ion is even if I don't specify a rel parameter the link relation is automatically assumed to be the name of the field so in this case self is the link relation when self is in a pre-approved Diana link relation but it doesn't have to be I an approved if your application understands different ones you can name this whatever you want as long as the client the server can can speak the same language very simple easy and intuitive and it supports HTML transliteration quite nicely so that's ions approach what about how sometimes people ask about this you know how is another linking technique if you've never seen it on the web and of course I'm biased but a lot of people think or at least those on the ion spec committee that how kind of fall short in a lot of areas it does support links but it forces you to create a property in your object model called or links with a bunch of other things to outside locations but that's not really contextually relevant is it so like for example if I'm if I'm creating an HTML document when was the last time HTML forced you to pull all your links out and stick them into an HTML element called links all right that's absurd links are most relevant when they're next to or combined with the content that's directly associated with that link and so how forces you to change your object structure or as ion allows you to just put it wherever is most contextually relevant so it's again much more like HTML ion so it allows transliteration by design and we're trying to keep things simple and easy understand we don't want you to remove the context from your document or move it in different locations for the benefit of a parser context matters so that's linking so if we're talking about linking in state transitions what does the state transition look like so I can get from one document to another from one resource to another how do I change state from one location to another how do I do things like creations and updates so you remember hey teos write the rules and hey teos about things being in the document most of us today and all of the api's and this is to be fair as is true of storm paths it was true of octa a lot of people don't do this but the answer to most developers today or the most that they take on is let me go look at the docs and I'm going to figure out how to do that post right we've all done this we've gone to the documentation developer documentation and we look at the URL and all the fields and properties that it supports and then we're like ok let me go code that and also code an HTTP GET and maybe I'll use curl to test it out this is not hideous right if you have to go read Doc's in order to figure out how to interact with an API that API is failing it is not restful by definition the fielding specifically says if you don't if if you force this on your users he does not want you calling your an API or REST API call an HTTP API or some other kind of API but don't call it restful so so how do how do we get around this or how do we address this how our browsers work all right browsers can submit state from one location to another how do they do it they do with forms right this is nothing new or special we've we've been using this for decades with HTML if I need to submit state or change state or from one location to another I have an HTML link or rather a form or the target location and a bunch of form fields so what does this look like in ion if forms are so natural intuitive how do we leverage them in JSON here's an example so this is a form and if you look closely it's just a link right there's an H ref property there's a rel property that tells you specifically in this case it's a create form there's a value right it's a collection we've already seen collection value objects before there's one addition in this case for HTTP support and there's a method property that says specifically it's gonna be a post and even this is optional if you don't have the method property post is assumed by default but and it's got an array of some fields right name login required true stuff right this looks very much like an HTML form so what is a form exactly what if we break it down what does it look like it's really more most importantly a collection of form fields right there's a set of fields that are represented to somebody either a user a machine client that represents the state the information that needs to be transferred so each field also has a type and a set of validations associated with it or constraints there's also a destination IRI or a URI right of where to send that information on on a HTTP transfer and there's also a method requirement at least if you're using HTTP as a protocol now if you're using a different protocol like TCP that method property doesn't need to be there you can use some other mechanisms of identifying updates or creates so I already has a collection concept right we've already seen in the link of destination IRI all we need is a rel to tell the client what type of link this is and these are actually pulled from Ayana as well well except for form but edit form create form query form these are already I in a link relation cyan is already defined this they know how value well this is and it's been around for four years so you know you can even make things way more complex and more rich you can have a link to create a user and maybe I have a collection of or visited continents and I want them to specify how many which continents have you visited or you can have the constraints like you have to choose one but there's no more than seven here's all the options right this looks like an HTML form this is not a surprise to anybody but if I get this in a document I don't have to go Redux I know exactly what's supported I know what the boundary conditions are I know what the permutations of the data can support everything is 100% represented in the document I don't need to read documentation search also works too so yes you're kind of getting information but you have to send data in to that URI in order to customize how those results are sent out and so you just use the query form link relation and in this case you know this will probably translator serialize to a URL with query parameters you know users question mark username equals blah email equals block serialization from JSON to URLs is trivial it's been defined in HTML for for a long time so if I have forms that represent structure and data and requirements and constraints sometimes we also get this question of what about JSON schema you know our take on this is it's it's it's not needed like if you've seen the forms example JSON schema is about defining what fields and constraints are available on a resource but it's really important understand that rest is not equal to our DBMS as far as the paradigms right create read update delete are not equal to crud I'm sorry get put post and delete are not equal to crud and and sort of to illustrate this Douce to do browsers need schemas of resource types no they only have one that they have to worry about in this 2h or XHTML specification that tells you the structure of elements in the doc but there's no HTML spec that says this is my HTML user resource this is my HTML group resource JSON schema is just a lot of us think is extraneous and not necessary because forms do the exact same thing right they show structure they show constraints they show what you're allowed to do but they're also more powerful and to that end or as an example what about forms that that accept all this information but you might have hidden form fields maybe like a JWT to retain private state across when you own you access that URL when you send that state from one location to another write JSON schema if it's representing a user or an account it's not gonna have a field that's represented for hidden State or field state or client-side specific concerns forms do everything JSON schema does and more their end according to fields Fielding's rule about dynamic typing they're fully dynamic I can access a field or sorry a form on one request and I can go back to that resource and the form might have changed maybe some in state or information has required additional fields to be entered or maybe they're missing because they're no longer required JSON schema doesn't really reflect that no in truth you could dynamically generate a JSON schema document to represent all these permutations but why go through that effort forms already do that for us so just keep dynamic typing in mind things can change and they should be able to change clients should always be able to go to new redirect locations and you know if you're if you move a property out of your out of your rest api tomorrow it shouldn't break a client because the client shouldn't hard code that that property will always exist forums tell you the structure of what's necessary so what about base URLs and versioning and date/time representations and pagination and async operations and long-lived ops and batches and clean errors and security and all this other stuff this is all the really good stuff that I'm sure you guys would love to dig into and unfortunately I can't dig into this in a 45 minute presentation but I would really love for you to participate in the the birds of a feather luncheon if you're up for it again I'll be available from 1:30 to 2:30 after that if you're interested in ion and you want to see it or try it out or understand the spec we're actually pushing to be an IETF RFC so we're going to declare a formal RFC that represents this that codifies this to be a fully comprehensive media type that is supports all of the radios concerns that fielding talks about until we become an IETF RFC you can check out the specification online at ímwg org for ion working group and the spec is right there you'll see everything we have one thing that we've not yet address an ion and that is the notion of custom constraints so let's say that you have a form field and you want to I don't know you want the values to only be a certain color maybe you want to create a color type for your form field and maybe that color type only accepts you know 16 different string literals blue green red or whatever right ion doesn't have a native color type defined just like HTML doesn't but it would be really convenient for you to you know be able to define your own set of constraints basically saying hey this is a string field here are the regular expressions or set of properties you know and this or these values that's basically custom constraint definitions and so that's the last thing that we have to finish and we're working on that now but as soon as that's done we'll be able to to go to the IETF with what we feel is a comprehensive spec that covers all all use cases so today then I've got a little bit of time left for questions feel free to chat with me today at the lounge again the the birds of a feather lunch right afterwards thanks for your time I'm happy to open it up to any questions so you said that forms are better because her than json schema and HTML doesn't really need schema but what about the differences between HTML 4.01 transitional strict html5 are there aspects of that that you foresee being able to add to forms like through versioning not saying that json schema is necessary because it does seem that forms is robust enough to take its place but is their natural definitions of versioning z' that within that that you're expecting to have built in natural definitions of versions for the structure of a document is basically what you're talking about um so yes so HTML does have different schemas for the media type itself a rather for the the HTML spec so there's HTML 1.0 1.1 transitional strict right you talked about these those are those represent the structure of what elements are allowed within an HTML document for all browsers right so it's really they could have changed the media type to you know applications less XHTML you know : version equals one but they also represent it as like a header right that you can tell what kind of version it is so but those versions are about the structure of the document or the media type itself that has nothing to do with versions of the the document that you're presenting in a request or a response so you can have you know HTML one document for one URL and then you could show 1.1 the next and depending on negotiation for between the client server that structure can change but it's not application structure it's not I need a new version to represent a user resource or an account resource or a company root you know what I mean so that versioning is really around the media type itself as opposed to the content within the if that makes sense and so forms allow you that Dyna Missa tee if you change your own applications content model and content structure and the parser doesn't need to know about any of that stuff so HTML versions and schema versions are all about the parsing of it does my partial as my browser need to change to look for these new elements right Google and Microsoft and all these websites still work because the browser can read those different schema changes but you can change your page from one day like we do you know our developer platform developer.com change dramatically this week but your browser didn't need to change because it already knew how to parse those elements even though the material content was very different if that makes them so forms allow you to do that and so to that end if things anion need to change or a neat versioning is necessary you'll have things like I on version 1.1 or 1.2 or 2.0 but you don't need a version field to represent your your document statement if that makes sense now you can add it as part of your self link right that's kind of your metadata for the page you can add that to give your your own application context that hey this is version 1 of the user versus version 2 and it's in the docs so that's that's good but the parser doesn't need to know about that because that's application level concerns so I know this totally breaks Haiti us but it makes sense to me to have the authentication and authorization in the headers and I'm still struggling to think of how the jocks and you know the the tokens can reside in in the links when they're temporal and and so that that authentication and authorization may not be accurate if you try to use that link a half an hour from now yeah so I mean if you only use HP headers and it's not in the document then it's not really hideo's compliant and so you're just you're you're coupling yourself to http which may be totally fine it just violates kind of the fundamentals that fielding was talking about so how when hey Dios do you so the rule for hideous is have it in the dock right there's nothing that prevents me from creating a document with a link to you know an authentication link that has a URL with an embedded JWT and I can click it and it'll take me to some page or I can represent a form of all the things that are needed to be submitted to an authentication endpoint and so for example maybe I hit slash user slash one two three and it doesn't and this is why I know Missa tee is so important maybe I hit that and if I'm being fully hideous it doesn't return me a user object it returns me an authentication form instead and then I fill it out and then I submit and then it'll return me the actual user if that makes sense no you can change the URLs for human empathy you don't wanna necessarily confuse people but everything I just talked about still represented as a link or a form in the document the HP header wasn't necessary at all now if you're leveraging HTTP clients to build SDKs for example it's kind of nice to use those HTTP mechanisms because it's codified their standards for it it's just not hideous and so what I recommend is if you're ever conflicted about am I being hideo's compliant or compatible if you stick stuff in HTTP headers add it in the document too and then you're covered like clients also depending on the complexity or their implementation may or may not have direct access to HP headers at the time that their word document is parsed you know a lot of times you'll have request or response pipelines and they'll strip the document out and leave HP stuff away and send the document somewhere else right well if I have that document out of the HDP context then anything that was a header I can't leverage when I'm looking at the document so if you're ever conflicted just repeat it in the document and that should never be a problem because clients shouldn't assume that it's always going to be there right they should inspect the document sometimes the link might be there may be other times they're not authenticated it's not going to be there at all and so Dinah Missa tee parsing the resource not assuming what fields are available is super key - hey Dios and it's really important for you bic wa t so you can hard-code fields leave them in in the resource but I promise you every time I've ever seen that my own API is included it becomes brittle customers break their their their their applications because they're just assuming that fields always going to be there it's not good so having an SDK that's dynamic that says here's the fields that are available but I don't know what they are you have to make sense of them is way more flexible and you will allow you BIC wa t across heterogeneous domains and in markets and verticals and stuff in terms of client adoption of Haiti us have you seen a lot of people actually like external parties implement Haiti us and follow it or do they tend more to see what the doc structure has read the docs and then hard-coded and just ignore that it's vast majority of rusty rest api's today require you to read Doc's to figure out how to interact with them and it's very unfortunate however there have been a lot of people keen to this problem and things have been changing pretty well last couple years so for example if you guys ever received an email from like Travelocity or kayak comm or whatever and you you get that email in your inbox and Google and it's Gmail reader shows you the departure date that the landing date and all this other stuff things like dang how did Google figure that out man that's so cool and you can add it to my calendar automatically the answer is that that information was codified in the in the SMTP email that was sent to you as state in the document and they also use something called json-ld which I don't have time to talk about today that gives machine clients contextual knowledge of what's in the document so like if I have a user name field the Machine doesn't know what user name is you might as well just call it bunch of random characters has no clue what a user name really is but json-ld will attach context to that user name field and say this field represents what schema.org definition of a user name is and so the the Machine client now knows oh I found this this field that has a context of user name attached to it okay I can treat you as a user name because Microsoft might call it a login you might call it a user name right other people might call it something else but json-ld allows a client to look at any of those fields and know oh this is a user name even though they call it a login this is using me even though they call it user name that makes sense so hey else is getting much better and contextual relevance around json-ld is getting much better and so really cool stuff like what that email example from from travel sites is all about hideous and so people are seeing the huge benefits of that and moving forward the biggest benefit I think is that regardless of what domain you're in I can interact with any third party whether it's Microsoft Google or Facebook or whatever and I can I can understand that document even though I've never coded or I don't have a facebook native SDK because Facebook is giving me the context in the document but that makes sense so things are changing for the better and much more so in the last couple years all right can I just suggest that breaking HTTP caching is not a really awesome idea that patios when you can't guarantee that a URL represents a known thing bright excited to be casually across the entire Internet wait so say Dios can't guarantee you are on what about the caching if you can't guarantee that the content of the URL is the same as what it was the last on the that you requested it then you got guys you can cache it it just depends on what semantics you associate with the caching right so you can set a header or represent in the document hey this is cacheable and here's an expires header or an expires member in the document that says it's cacheable for this long like we won't change it or it's not going to be that the relevance won't matter for a certain amount of time if your api is so dynamic such that things can change dramatically across resources that just means you won't enable caching for that resource or that end point if that makes sense so caching is totally plausible and feasible it just depends on what context you give to the cache and how long you're saying it's allowed to be cached for by the client so that's not precluded at all with with hey Dios it just depends on how dynamic do you want to be you know are you gonna constrain yourself to not change that doc or are you gonna tell the client you can't catch anything because I might change at a moment's notice either of those are completely legal that's a choice you have to make based on your application Thanks I'm out of time at the moment but thanks for coming in again I'm going to the the the Lunch and Learn or the birds of a feather feel free to join me there otherwise take care of have an awesome afternoon

Channel: Okta

Views: 34,493

Keywords: REST API, JSON APIs, Oktane17, Okta

Id: MiOSzpfP1Ww

Length: 48min 13sec (2893 seconds)

Published: Tue Sep 05 2017