 Okay, everybody hear this. Okay, this is a bit bit of a departure from your typical Presentation fair, but I hope it's okay. Welcome to API design the musical No, really got the guitar here. We will be doing musical sessions So a lot of a lot of times Drupal con sessions are named pretty creatively I think we all enjoy having a bit of fun with those but but this is truth in advertising so We're gonna learn about How to make your API API designs successful? We're going to celebrate the storied career of one of rock's most enigmatic groups API design who took prog rock one step further and Made it programming rock. I'm David Dears. I'm from Fort Kitchens. We're in Austin, Texas. We make big websites I've been working with four kitchens for nearly four years now and doing Drupal as my full-time development job for a bit more than that and Before that cold fusion. So any cold fusion guys out there anybody? Oh, yeah I'm serious. It was terrible. Okay. Anyway No offense Ben ford and we love you. All right. I Do have a special interest in databases and database schema design and that's probably into a sort of a love of making API's and Understanding what those are my recent work has been for media companies doing API design and implementing API's with restful with Drupal And something I really quite enjoy. I thought what I would do Is pay tribute to that great band API designer tackle these kinds of issues in Song and words but also try to give you a little background on each of those songs before we get too far into it I have a double life. Not only am I a Drupal developer by day. I'm a classically trained composer I got my master's from the University of Texas at Austin a study with Kevin putz who is a Pulitzer Prize winner in 2012 I believe or 2011 and I felt studied with Stephen Slawek who's a master sitar player He's a disciple Ravi Shankar very lucky to study with him for 11 years So and just in case you're looking for something musical do tonight. I'm playing Coolix woodshed at 8 p.m. In North Hollywood. Okay That's a live tape and thank you very much. All right so first of all and Feel free to call these out. Does anybody know any companies out there who offer a web API? I just feel free to shout those out. Yeah Go ahead Yep Yes Yes Yes Yes Yes That's just the top of our head so we can kind of tell that you know if we just even put our minds to it we'd come up with a million of these but It is it is a brainstorming session just like this that the band API design wrote their very first hit These are some of the API's that I know from the very first album the man in zero zero zero zero zero Google Maps Trilio YouTube Wikipedia who is Facebook Apple store MDB play skin spotify Netflix Will a work at the asensis girl at seven dictionary try this song gig vimeo. These are just a few of the apis I know All of these companies There's so much functionality to supply all of these companies that got their own new fangirl Safecast Pinterest square cash a will Bitcoin and the metrics finish every super dots get up So sales force genical be a man SNLE they will come out of the area's answer near time. So low These are just a few of the API's I know Why it almost seems that every company out there has an API Some are good Some aren't so good I guess it depends on How well they were designed Quick books around the labs rumble fish linkedin red a sound down and be our event bright male champ UPS Ted talks expensive by hoolie fight fiber. Okay. There's don't exist. I wear a group on drop-up shut up Oh, these are just a few of the apis. I know These are just a few of the apis. I know Thank you very much, of course, that was a huge hit for them way back in the 70s. No, that's not true So with with web API's Basically, these folks are surfacing the value of their businesses and their back ends and their platforms by producing an interface To the functionality and making that available on the web That's what a web API is all these companies have chosen to do that It's a part or all of their business value. So this is a huge thing Just for this list alone just from that from that simple song. It's and it's in no way complete There's a ton more apis out there. We can see that there's been a proliferation of web apis and that's been great Not great because right now in the world of web apis and web API design We're kind of in the space that PHP applications doing CMS work were before Drupal and before WordPress That's the Wild West of API design. So They're wildly different in design and implementation details. They're all over the place and you kind of have to code to each one So can't have a lot of reusability in your code and it's kind of a nightmare and the patterns of use are kind of Not yet risen to the fore. So we hope to change that through Education efforts like this one to kind of get people on board with a new way to think about web API is a more reusable way So there is hope just like PHP web applications began to discover useful and reusable patterns like Drupal and The way that we work with CMS is in WordPress and Drupal So we codify that approach and we can do that in API design So it's the Wild West but the Wild West was tamed So how was the Wild West one well just like cultivating uniform approaches and best practices in PHP We do the same thing with API design We can create strong standards that are going to allow us the same ability and freedom that we had when we made that remarkable step in PHP to innovate and iterate on those designs with tremendous fury And that's the best possible world for API design and for web API's because all of these disparate API's Can then act in concert and allow us to begin to innovate not only in isolation But in a shared community like we have here. So we have Drupal conference amazing event I love this thing. It's why I got into Drupal development in the first place That's why I wanted to work for four kitchens. I've been doing that for the past four years and they're really loving I'm so happy about it. I hope you're having a good Drupal con LA experience of this year for anybody's first Drupal con out there. All right. Yeah Welcome to the community. Thanks for coming So when we talk about web API's How can we tell, you know, if it's designed well, what are the dangers of having a poorly designed API and really when we do Talk about web API's what exactly are we are we talking about? So This is of course the interface pattern from the Fowler book so not to get too geeky, but wait, but that's in fact what it is we're writing a way to abstract and present a Backend that we don't wish to expose our implementing methods or our implementation and we want to give people the ability to have that functionality through much simpler interface And so in order to really be successful with web API's you need people to use them and part of that's going to come from the value of the back-end systems that you're exposing through your API but It might not you might have a competitor or two and if you do and even if you don't good API design can be a Differentiator in your space. So if it's a well-designed API and developers like using it enjoy using it They're going to do original things with the functionality that you've exposed extending your business value way beyond You know what you might have originally thought you might not even have those ideas But by developing a well-designed API people are taking that and extending that and doing wonderful things and combining it with other API's making mashups and other powerful technologies so Why but why design at all, you know, we're a natural shop we iterate on stuff Why not do that with an API that that seems like a good idea, right? Well, no not not really It's kind of bad because unfortunately with API's You sort of a silent contract when you release your first public version of that API with Folks who want to implement clients against it Whoever they might be and that contract begins and they begin to expect things from you from your API This is how your API is going to go. This is how we're going to use it This is what you're going to provide and that's going to be there forever, right? You never would want to change that so I'm just going to implement my client and we're going to be good and it'll work for the next 15 years. That's how technology works, right? Right now That's not right. So you might then there might only be one implementation on your API and they may never come back So make it a good one make spend time on your web API design make sure that it's useful and there's some ways to kind of do that and When we when we think about you know, what makes a web API design good? What are the what are the properties of a well-designed API? Well, the fast answer is is it easy to use? When clients implement your API does that generally make sense when you take a look at it from a distance? Does your API think of a computer is just another kind of user is it robust and is it sensible? So that's a fast answer the long answer the magic fortune cookie answer is sort of you'll know it when you see it and we're going to teach you how to see it and These are exactly the kinds of questions and answers that the band API design sought to answer in their Ballot of the web API from bringing it all 127.0.0.1 application programming in a phase by the complexity of code away Couples your code from your functionality and Opens up your systems to a host of external originality There are internal API's and ones that have a public face They all expose them back in functionality in simpler way greatest hits They could do a lot then modeling your API I own it and it's true. It's from the API. It's a silent contract You're telling every API developer and client just what they should expect Couples to your back end Then the problems will be hard to amend It's easier to add than recent Legacy support seems to never end. You've got one chance for a good version one So why don't you take your time? Put your efforts into a good API design It is hits And you could do as users keep the architecture of the web in mind Is it easy to use? Is it robust and extendable too? Does it have client code that is easily understood? Thank you very much That was their their Greenwich Village phase, of course to sort of keep the architecture of the web in mind Then making your API a restful API and we're going to talk about what rest means what a restful API really is right now and You know the band tackled that issue in their 80-minute double album Odyssey restful got a divita Which is a huge concept album, which is the entirety of Fielding's dissertation on rest Which I'm not going to perform for you tonight Thank you, if you can see me later, we'll have a beer about that But who is Fielding who's the guy who sort of went through this whole? Dissertation well, he's a very important gentleman because he wrote the RFCs for HTTP 1.0 and 1.1 so he knows a few things about the web and the web had been around when he kind of put this to pen put this to I guess Computer keyboard move past the time of pens back in the World Wide Web the early days anyway and It first dissertation he tried to codify and describe the how and why The World Wide Web was successful and he had lots of years of experience at that point to kind of draw some conclusions And kind of see the broken parts at that point And that's what happened in 1.0. He sort of described all that and then by 1.1 You know a lot of the problems with HTTP Improvedations in 1.0 and the web were kind of fixed as a result of his restful descriptions So it's actually pretty neat neat dude The key parts about restful The key part of restful for API designers So restful is the way that the World Wide Web works the web pages and browsers and all that and it makes a lot Of sense and it describes all that so the idea behind Emulating that from an API perspective is that it's a proven successful technology These are native methods to the web if you have a web API you should use those native methods You should adopt the the reasons and the why's in the house that's a internet Sort of web pages work and are successful So for API designers the important part of restful from fieldings dissertation are that we have very very short sessions Clients and servers really don't know much about each other than a brief handshake that they do over a very short period of time The building blocks of API's are these this idea of resources and those resources are not resources themselves Representations of those resources and we'll talk a little bit about what that means Clients clients who consume API's Through rest restful clients keep application state basically and then servers tell those clients what they can do And that process is called hideous, which is a mouthful which we'll also look at in more detail and the final thing which we will look at A bit more in detail is that clients manipulate Resources so clients have a resource the server sends the client the resource The client may want to manipulate that resource and it does so by sending a representation of that resource Across the web using methods that are native to the web HTTP methods, so we'll talk a bit about that as well so And why am I doing this well because if you were able to hold these principles in mind these restful ideas in mind Basically they can guide your design decisions every domain out there might be different from another And so the exact specific details of what you should do or what you shouldn't do it might be dictated by your Content types your media types you may have specific Domain specific content types that don't don't really allow for additional things, so I could go into all those and we'd be here for two Hours or three or four maybe a couple days I don't know but the point is that if you can hold these principles in mind that you can sort of be guidepost you and Basically prevent you from becoming you know all-star track, which is going where no man has gone before With your API design, which would be a wrongful headed thing because it can basically inform you whether or not you're relying on well-known Improven native technologies versus going cowboy and inventing your own thing, which is going to be a mistake here Just a brief edit restful got a divita Will not play the 80-minute song for you But but just a small portion of it to kind of get a few of these concepts through that API design the band tackled This is restful got a divita Representational state transfer. That's what rest means to me Client keeps applications state and server gives transition possibilities on people that hate yours. I just call it great RESTful clients manipulate resources ascending representations of state What made the wham so great? I Seize for properties and non constraints restful At least that's what fielding said in his doctoral degree. I think we can trust fielding. He wrote the HTTP RFC property one There's a low barrier of entry The web succeeded because it was easy. I like to tell that or go for Property to extensibility The web to change for new requirements. It wasn't stuck where it was and its original limitations And here's where the first edit takes place So I cut a guitar solo and a couple properties because they're not you know They are relevant but not as much and so it's 80 minutes So there's a killer summation of all of this stuff however in adminsons book restful web APIs and this one of the appendixes and it sums up the entirety of RESTful guided to Vita in a beautiful way Representational state transfer that's what rest means to me Client keeps application state and the server gives transition possibilities on people go that radius. I just call it great RESTful clients manipulate resources ascending representations of state RESTful Serious of four properties and then constrain At least that's more feeling said in his doctoral degree. I think we can't trust field and it wrote the HTTP RFC Constraint number one the identification of resources where every resource gets its own URI Talking about the properties of addressability Strain number two the manipulation of resources through representations We talked about this briefly but Clients and servers exchange resources by sending them complete or partial representations of the resource along via native methods Constraint number three self descriptive messages or standard methods and media types are used to indicate application semantics and a stateless series of transactions that contain all the information that a server and client need to know about the current or desired Savory resource strain number four That's hypermedia as the engine of application state This one's a mouse mouthful. I couldn't even say mouthful. That's how much of a mouthful it was We're gonna come back to it later, but briefly hypermedia controls like links help applications control and manage which methods and HTTP in this case that are used to manipulate resources And here we've cut down an orchestral breakdown a poetic reading by Morgan Freeman of various portions of the field in dissertation Don't worry if it all flew by we'll touch on the important parts later And that's the edit the single if you will have restful got a divita. Thank you very much Okay, man. That's a long line even even the single is sort of long So I want to touch on three parts of this I want to take a look at resources in more depth I want to look at hypermedia hadios because that's confusing concept from an API perspective And I want to look at HDT methods a little bit more closely. So each of these things are going to fill out our Our understanding of what rest is and how it applies to APIs And of course this was tackled in resource calling the seminal punk record from API design Where they sort of talk about resources in a little bit more depth. So let's take a listen I did some URL Resource can be anything like a book or a Taco Bell Clients don't care if it's a man or a station because all they ever get to see is a resource Representation got your resource. Don't worry about the rest Of course, they're not the resources the things that represent them in state Representing resources in state Rest is representing resources in state each resource has a media time Could be XML YAML or JSON and then there's extensions that out on capabilities and formats Tell clients about functionality and presentation With clients still on the kids to see that resource Representation out the rest Of course, they're not the resources with things that represent them in state Representing resources in state Rest is representing resources in state Thank you. Thank you The main idea being that Thank you very much the main idea being that resources are individually addressable that usually means that a URL canonical URL They take Content types or media types. They're different ways to express the same thing but the idea is that they might be JSON formats or YAML formats or XML formats and Inside of those resources are a series of attributes that describe the the resource and when I say resource I'm using that a shorthand what I mean are representations of that resource So that representation has all these attributes to describe that resource that could be a full description of the entire resource every Attribute ever ever restored about this thing or ever in some way representing it or it could be just a partial representation of that resource And And and the idea that it also could be anything it can be a book can be a person it can be stored can be a shoe can be Anything you can think of it can be a research could be a data database field. It could be a configuration These are all resources and these are the building blocks of APIs If you do any sort of any exploration of resources on the web So go if you go to any of the APIs that we listed in the very first song Where we had you know get a Facebook Amazon You'll start to see that the sort of lingua franca of the web and resources is JSON This happened to win over an earlier format, which is XML and soap for web APIs Part of that and that's a long story and maybe it's not over yet But for the moment does seem like JSON is the sort of the winner of this of this comp contest and they offer different things But the reason JSON seems to be so successful. It's ubiquitous. It's all over the web, right? It's it's in your web browser It's it's actually a pretty powerful format. It's small But it is very useful to describe all sorts of things and that's what you need for resources because you just said, you know They can be anything so if they can be anything you need something That's pretty flexible pretty simple to be able to get into that and describe those things with the relative ease Problem with plain JSON is that the native format of JSON doesn't have an idea of hypermedia There aren't links. So it's a world without hypermedia and we have put this down here at the bottom this comes from github and What is that? What what is that in JSON? Is that is I mean when you look at it? What does it look like? anybody It does look like a link. Thank you, Paul But it's but it isn't a link. It's it's actually just a string There's nothing you and I by looking at it as programmers. We might consume this API and say oh, this is clearly a link in fact the title the attribute name of this is Says it's a URL. I'm going to use it like a URL I'm going to go to it and I'm going to do something or manipulate a resource there using this URL But a machine doesn't know that unless I tell it to and when I tell that machine that that's a URL I've coupled my implementation. It's not a strong It's not a strong implementation anymore It's pretty weak and fragile because as soon as they change that or if someone doesn't enter in a URL or it's no longer a URL There's nothing to tell me there was your I was just a string. It was always going to be a string It's how my machine understands it except I told it something different and that's the kind of a disempowering aspect of JSON, but we're not totally out on a limb we can actually Use hypermedia controls in JSON by extending JSON formats We can Yeah breakfast. Hey DOS basically Thank you, Matt So hey DOS is hypermedia as the engine of application state and that's like telling us basically the server is telling your client Hey, here's what you can do with this resource. Here's what to expect when you do that with the resource Here's the kinds of methods you need to manipulate that resource Here's what you can't do with that resource and that's what hypermedia Really does in the context of an API you know the word hypermedia from html markup. I hope or or I'm telling you now So it is what connects documents to document It allows for links and images and other embedded resources within your web pages So that's kind of what it is in the world wide web for browsers for API's The real strength of you know hypermedia for API's is the ability to connect resources to each other So basically without hypermedia for resources every resource you went to is an island and there's no roads to get away from that you might Figure out something that looks like a path there, but it's not actually a path. It's whatever you think it is You know, it's it's a string. It's just not a link But hypermedia Enabled JSON formats actually allow you to go from resource to resource To link to them to link. Hey, it's great So they I guess the main idea that is if you if you don't use a hypermedia JSON format If you just use plain JSON as so many huge companies have chosen to do what you're basically saying is I You to all of your API developers you're going to implement some kind of client for your API is basically I'm not going to You need to implement to me and Every company is going to implement a different way to indicate links gonna have different kinds of names for those things every Client that is coded to one of those is distinct and coupled to each of those API's and that seems pretty lame And that's why we have hadios hadios Which was covered in the don't worry be happy Album from API design Basically is going to allow us to use the power of links to connect our resources. Let's take a listen With this resource I have What methods can I use what kind of response can I expect? Will you show me? It's relationships hypermedia remember hypermedia from the internet It allows you to link from document to document Well in the world as does much the same Connects resources and describes them in machine readable ways And without them every resources in our land Can't use any library of ways to get from place to place Hadios Come to ask of you again with this resource I have Methods can I use what kind of response can I expect? Will you show me? It's relationships Hypermedia and links are the true power of hypermedia and API You can rely on two elements that they do provide There is a trip which gives a location of the relation to your quest And there's rail which gives you sense of where the lake leads in context You can try sites like IA and A or provide your own Let's give you again this resource I have use what kind of response can I expect can you show me? It's relationships Hypermedia Thank you When we have links in in resources We they do expose these two properties which are pretty key They have the href property which you probably recognize from you know your a tags in html Which leads you to you know where you're going with that link So basically where am I headed to it tells the client the rail part of that which is another property of that link in in an API Exposes that the relationship between that link and the resource you're on so it might be in the example that we saw a couple slides ago Which I won't ask you to turn to You can so in this example which is from the house spec. This is a howl implementation of links So it's in JSON howl is a hypermedia capable format We can see here that we have a section called links and within that links the rails are actually the properties the attribute names And then we have an href which leads those links. So I think this is for books or something like that. Is that right? Yeah, and so we have the self which is pointing to itself and then we have well, here's the author and Our warehouse and invoice where this where's this being stored? But there are basically domain specific Relationships that are that are named at I a and a and then these these slides will be up online And I've actually pointed to that so you can go there and check that out Or you can define your own when you do define your own You need to make sure that the world understands what you meant by that So and we'll get to that in a second which is this idea of profiles and profiles strengthen the power of hypermedia because profiles then tell machines or human beings What all these custom either attributes or relations that you defined in your resource mean? So I have a bunch of attributes that I've created because I have a domain specific problem Which wasn't solved by a media type that exists. So I added these to JSON or howl or whatever my content media type was so And and those definitions then were explained in the profiles which could be human readable docs Preferably their machine readable docs and a machine readable profile format and there's several of those and I encourage you to go Out of the web and take a look. I think there's three good ones But anyway profile so that that's what strengths and strengthens your your hypermedia and really informs people what what all of these link Relations mean without that people are kind of in a guessing game because no one really knows what you meant by your attribute name Natural props it just doesn't make any sense to anybody besides you and natural props is a stupid example You'll have much more well thought out examples, but people still be equally confused unfortunately Tornado down there. So finally, so we have resources which describe, you know, the representations of the data They're all of the things that are important to us that we're exposing from our back-end systems from our platforms And then we have hypermedia hideous to tell us hey now that I have this resource What can I do as an API client? Can I add a resource? Can I edit this resource? Can I tell you I want to do something with it? Can I delete the resource? What are the what are the kinds of things I can do with that and that almost completes the picture except that we have No way to actually do that until we add the HTTP methods and we've got several of those which are all native to the web Which makes it restful which is great. We've got git post put patch kind of the same kind of not and delete Which performs sort of crud-like operations on our resources So, yeah, but I actually just want to have a read API. That's fine Not every API has to blend and implement all of these resources and not every resource collection or set of resources Needs to implement each of these methods equally. So I might be able to read and write to books My API might be a books and I'm working with providers of books who are going to tell me what books they have available And they can read and write But I don't actually want them to delete any because even if that book is no longer published I'm going to record that at one time it was so I'm not going to allow an API client to do that and that's totally fine There's there's no need to have all of these things equally supported from your rest implementation your rest implementation server So but what you must do as a server and plan for as an API designer is the providing of status codes about What happens when a client does make a request and with one of these methods? You as a server have a responsibility to say okay, that's cool It succeeded you did a good job or not that failed there was a problem You didn't format this correctly you were not expecting this in this format various things like that So you do have the responsibility to provide those status codes back and luckily There's a whole series of standardized response codes that you can leverage and you should use the standards don't event your own It's a dumb idea so Basically, we have we kind of have a map for the cred things I said cred like because it isn't exactly cred but close enough for this talk for the purposes of this talk So basically git is kind of like a read. It's it's a safe operation We can go out and grab as much as we want to get all these resources understand what they are post is like a right We're gonna write to the system put in patch or kind of like edits And delete is very much well Like a delete so And this was put into song by our favorite band API design from their appetite for destruct Album in a song called git post to put patch delete Get post put patch to leave the main methods of HD If you want to read or modify your application state use one of these methods or another And the HTTP request to me Now there's get it's a little like a read It's how the resource you do retrieve And it's safe. That's in the RFP 2616 retrieve resources, but leave your app state pristine And if everything works out With the git request you make You receive a status code of 200 Okay, and there's post which is pretty unsafe It's how you might a resource create The representation you'd like to add Now it's up to the server if it will do just what you ask If everything works out With the post that you do You'll get a status code of 201 creative accepted 202 Get post put patch to leave main methods of HTTP If you want to read or modify your application state use one of these methods or another In the HTTP question me Like to mention two more methods that you might see if you're poking around with best full HD There is head, which is like it but nobody And there's options which tells you which are the methods you came here Which are their updated resource? All the patches just in our FC And with put you got to send things you want to change in their entirety Whoops One more time and with put You have to send the entire representation But with patch you only send the things that you want to change And if everything works out With the update you form You'll get a status of 200 no content 204 And finally delete Does what you might guess Rather ask the server to delete at your request And it's not safe It'll change your application state And it's entirely up to your server to decide your resources free If everything works out And the resources no more You might get a response with nobody of content 204 It's of HTTP If you want to read or modify your application state Use one of these methods or another in the HTTP request you may Why thank you Okay, well So all of these methods are going to allow you to manipulate those resources as a client When you delete a resource you send a partial representation of that resource or a full representation Whatever is required by the server and it's going to tell you what is required with the status codes Or your profile or your human readable docs And when you send that method It's going to ask the server, hey delete this If the server wants to do that because you have the authorizations then Basically it will do that and will tell you that it has done that through a status code Same for the rest of the method. So it's the way that resources are manipulated With rest brings us to the power finally now we have all these ideas in our head about rest What restful means which brings us to the power of api design a basic process for this It's very very easy Which is to kind of two two things and this is again From the restful web api's book from mike adminson, which is a wonderful book. I encourage you to read it If you want to know more on this subject What he states and what I think is a great idea Is really is a basic process what you're doing is selecting a content type a media type Which is going to be you know, I would recommend a hyper media supporting Json content type that's my experience and that's what I like. So perhaps how Perhaps iron perhaps json ld and there's a lot of different options You want to choose the right one for you? There may be a Domain specific media type for you and that would be the right choice So you do need to take some time spend some time to look into that But basically you're going to choose a media type and then you're going to come up with all the attributes You need whatever isn't supplied by your media type and you're going to name those attributes You're going to name the hyper media link relations between your resources so that computers Computer users basically computer clients have a way to understand how these resources are related to each other And then you're you're done. That's the basic process now. Obviously this can get a little bit more complex So we'll we'll talk about that for a few minutes. I do want to leave time for questions, but um So So the early stages obviously you can't build something if you don't know what you're building Do understand from your business clients what it is they want to accomplish with the api What part of your back end you want to expose? I hope this is a collaborative effort with you and your business team or your business team is really bright And they're just going to tell you what to do, but um Either way you have to understand what is your building as a api designer You should be really familiar with the data you have in your systems So that may mean drawing an anti relationship diagram that may mean looking at the database tables That may mean looking at your content types and understanding what is being recorded in your systems that you have to say If Drupal is your back end here, you want to look at the content types decide what those fields are What kind what types of fields are they what are their names have the whole that at your hand Be able to understand what that is so that when you are creating these resources and naming them custom things you are Drawing from the information that you do have and the relationships that are established in the systems that you're using One thing i'm going to caution you on though is don't take a database field and make that a property on your resource Don't take a uh field from Drupal and make that a property on your resource That would be tightly coupling the implementation if you move to Drupal 8 for instance In fields just aren't named the way they're named anymore You've tightly coupled that and now you have to figure out a new way or break your api or release a new version And as i mentioned before you really do have one good go you can release New clients, but you're going to have to figure out how to phase out support for those clients over time so The next process that you go through in api design is for the reconciliation and that's like you've spent time leveraging the Efforts and the people hours of other people experts in your field who have taken All many many years to name Data in your field. There may be specific Implementations of that like media types that are specific for your domain like mapping Or there may be things on schema.org where people have taken time to name say you're a television show or media show there might be Specific relations between shows like producers technical directors and named in a very specific way if you use something like From schema.org or any of the other expertise organizations out there that have named data and have gone through You know a vetting process for that You're going to have a stronger implementation because it'll be shared with you and maybe a few others Maybe quite a few others and that's going to make it a reusable space So if someone can read uh Because you've used schema.org's definition podcast Maybe another podcast consuming client can just go to your api and start consuming without having to write any custom client code And that's really the power of the standardization. That's why we go through this process of reconciliation and figuring out Can we use anything that is a standard out there? And so if you haven't come to choose a media type at by this point in the design process It is time to choose and my recommendation for you out there based on my experience is that if you have a read Only system out there go ahead and use how I think it's very useful for this There are implementations that are ready to go ish In drupal modules out there. They may need a little work and we're working on that and we'll get that out there It's fine But but a lot of it the work is done for you in these spaces And so I do recommend how as a read only hypermedia content aware json type If you have to do read and writes not that you can't do that with how or html or anything like that, but you do need to understand that The hypermedia support for other operations outside of read for how is pretty weak It's there. You can obviously support posts puts patch edits We're doing it in one of our projects, but it's it's not a strong So that's going to have to come down to human readable documentation or profiles. It won't be there from the resource itself. So And then sort of the final steps Make sure everything is documented make sure all your attributes are documented make sure all your Relationships are documented between resources This could be human readable. It could be machine readable And I think we've made a good case for why it should be machine readable And then you want to make sure that's published You want to write code samples the more code samples write three and you've got a very solid api right two It's okay right one. There's going to be problems So if you can if you do have the time if you're afforded the time to write clients against your api as examples and documentation Please do that And then finally if there are any authorization instructions for getting an account and being able to write and read You want to make sure that's clear to everybody else and then you can release your api and so This is The final song yeah, thank you very much we have about Nine minutes for questions and all our time. So I appreciate your Patience and this is the first for me. So I hope it was okay to do kind of a schoolhouse rock musical presentation on coding Pretty pretty interesting thing for me to do and I hope it was interesting for you. So thank you all for being a great audience Thank you so much Could you back up one? So yeah, okay, I do I do want to say though if you wouldn't mind filling out a survey I'll take all your feedback on this I know there was a ton of information that I sort of spit out in a very fast method And so I'd like to figure out how to make this a more valuable presentation for people But still have a bit of fun. So any feedback you have please go here and let me know Now where's the free bird too you got to play free bird, all right But do we have any questions about api design? I know we'll say this the if you have any in-depth questions about implementation in Drupal Headless sites or anything like that. I'm happy to talk to you about that find anybody in a green shirt And in a green four kitchens jacket and they will point you my way I'll be out on the trade floor today and tomorrow And happy to talk about this in more in-depth, but any questions Ah, that yeah, that was the no rest for the wicked. Uh, yeah the album from api design, of course Um, you can well, uh, you can implement the options header, which might Thank you. Thank you, uh, the question was uh that I that I had said earlier that we don't have to support all the Http methods on each resource. Um, and is there are there any standards around Providing information about that was that is that right? Did I get that right? I'm sorry To tell the client that we don't support it. Yeah, okay. Um, if you have used uh hypermedia aware Like siren or something like that you can actually tell the client on the resource itself What methods you do support so you can say you can do a put here You can do a post but you can't do a delete If you don't another option is the options header, which uh, if you if you support the options header on your resource It will basically tell clients. What are the available methods on this resource? And if they're not there, they're not supported If neither of those is an option Clients will sometimes just go ahead and try to do stuff and then you're going to send back to that As saying this operation is not allowed on this resource. We don't support the chttp method So there there are alternatives there and that would be kind of like a last step if you if you didn't have the hypermedia support in your resource Yes, wow, I actually don't know about that. I would like to talk to you about that afterwards Uh, and that was about swagger. Is that right? Fascinating. I actually don't but I will form one as soon as I figure out what it is Uh, sorry about that. I'll look into it. Thank you Andrew man What would be an example of a customized people? Uh, what would be an example of that? Oh, really? Okay. Interesting. Wow. I'm not sure if that I'm not sure if I feel that's very restful, but like But yeah, but um, I guess Definitely, it's going to be in the profile. I suppose I think, you know, general advice is to sort of avoid custom Http methods So if you cannot all avoid it, that would be the right thing But sometimes sometimes you're right there like the cred methods just don't fit their case And then you have to do something weird And that's why maybe we get into the space where things are restful and not rest pure. So My own opinion and this is all in my opinion. It's like put it in options say it's available Documented from your resource From your api home like where to go Documented if you have a hypermedia where content type indicate what it does there document the relation For the if there's a cash resource document that relation in the profile, I think that would be what I would say Does that make sense? What what what do you think? Then you can use delete or or edit or whatever you wanted. Yeah, exactly. So maybe that's the solution just Basically, if it's not in the if it's not a resource into your api Your clients aren't going to see it. So you can get into trouble if you haven't resource your Resources, I guess and and then you have doing maybe weird things and like well I don't know how to do this because we don't really have it Well, if you don't have it, you don't have it. So if that makes any sense, I'm not sure it did. Yes Automated generated documentation Let's see We I guess in in my experience. We've done we have not we have not I think it would likely be possible in some ways You should restful apis Don't need any documentation. You should everything you need if it's hypermedia aware You know where to go. You know what the relationships are the attributes describe themselves They link to a profile if there's any additional custom attributes or relationships in there, which are understandable. So And I guess that that would be the documentation But you might not even need that if everything was sort of clear enough or you use standard Relations or you had a standard content type that sort of had all that described So you wouldn't have to provide any additional, you know documentation. So Yes and no, you know Certainly done enough documentation by hand that to say that that's probably the way that I've done it thus far Yes I think there's a there's a case for either depending on Your application what you want you could make a relation out to the to the image and if that if like You're a photo app or your photo api that makes a ton of sense. So you're relating images in a photo album Or they're tagged and you're you're going to all Tags the family and there's that's the relationship for those images and you're linking directly to a photo album Or you're linking directly to an image from an image That has some relations. So there'd be good reason to break that out into hypermedia links there would I think that's probably the strongest answer. Yeah to go ahead and do that Yeah, if not, then you're tightly coupling what what's going to happen, right? So and then that's like less desirable Any last quick questions, I'm happy to answer stuff in the hall. I don't want to hold up everybody here I've got one minute. I'm totally burnt out the next guy. So Thank you all so much. I really appreciate you've been a wonderful audience Thank you. I'll see you on the trade floor. Cheers