 Good afternoon, how nice to see you all. I am very excited about giving this talk, but I wasn't quite expecting so many people. So I can only say thank you very much for coming along this afternoon. I'm going to be talking about REST, and this session is aimed very generally at web developers. I may as well say now, before it becomes any more obvious, that I'm not a Drupal expert. I'm a REST expert, that's what I do, I love APIs, I care about APIs. I spend most of my time in either straight PHP or any one of the other PHP frameworks. I know a great many things, none of them involve Drupal. Basically the only thing I knew about Drupal before I came to DrupalCon is that I like to drink with Drupal people. So I was very pleased when they accepted my talk. Awesome, so I have some giveaways for you. I will do that right at the end of the session when I take questions. So if you ask me a question and you're in the first two people to ask me a question, I will give you a copy of my book. If you have questions at any other point during the session, I am totally happy to take interruptions, but to get my attention you should go to the microphone because you can't ask me a question until you get there. So don't raise your hand, go to the mic, and that way the people listening to the recording will hear it as well as everybody behind you in the room. So, here we go, REST. REST is all about data. The acronym stands for Representational State Transfer, and it's pretty much what it says on the tin, right? So we deal in transferring representations of data. Everything is a representation of a resource or of a collection. And we probably represent it in JSON, in XML. Maybe you serialized your PHP or you like YAML or Klingon, or I don't really care. But you represent your data any way that you want to. Every thing in your system is a resource. So a user is a resource, an article is a resource, a comment is a resource. We consider everything as a resource and we transfer representations of it. When you're getting lists of resources, we call those collections. Like most very hyped technologies, it's mostly about the words. For a thing, you should say the word resource. And for any kind of list, you should say the word collection. Now you're a REST expert. It's not just about pretty URLs. You do need to have really good routing to do REST well. But the URLs are very important. They tell a story. I have some example URLs on this slide. It's that the top example, slash articles, is a collection of articles. You might guess that articles slash 2756 is an individual article resource. You're all with me so far. This is excellent. Also you will see these sub-resources. So I have a specific article resource which has a comments collection associated with it. Rather than getting all the comments in the world ever and filtering for this article, we can make them available as a sub-resource of our article. Then as an example, I've got an independent, an individual comment resource. Those URLs pretty much describe the data that exists at those URLs. Thinking of data being at a URL is a really good way to think about how this works. Typically, when we talk about the web, we are talking about using REST with HTTP. That means that this talk is about REST and it's going to involve quite a lot of HTTP because that's the example that I'm using. HTTP is an awesome format. It has lots and lots of features that make implementing elegant data transfer very, very easy. I am going to talk to you about verbs and how we use those in a RESTful API. I'm going to talk about status codes, why they are so important, and under what conditions I will hunt you down and kill you. I'm going to talk about headers. I want to talk about how those fit in, also in the context of a browser and also of a mobile device. I've got some examples for all of those things. We'll start with verbs. Verbs define the operations that we perform on our resource. We use the same URL, regardless of whether we are reading a resource, creating one, changing one, deleting one. The verb tells us which of those things we're doing. As web developers, you already know about GET and POST. I'm going to add two more into that list for you. That's the put and delete verbs. When we use the GET verb on a collection, that will fetch all the resources in a collection. We'll get representations of each resource in a collection. If you do a GET request to a single resource, you'll just get the representation of that resource. The representations are the same, regardless of whether it appears in a collection or as an individual resource. We use the POST verb to create a new resource. You make a representation of the resource, you craft together whatever representation language you're going to use, and you post it to the collection that the new resource will live inside. It's a bit like doing an insert on a MySQL table. You just send the data without the primary key, and the database comes back and gives you the last insert ID. In this case, the rest server will come back and give you the URL where that resource will exist. We use PUT to change a record. You would get a resource, change it as you need to, and then use the PUT verb to put it back where it belongs. I have created in brackets because you can put a new record to a known URI if the client gets to make the decision about what the URI will be. That's not often the case, hence the brackets. Guess what the DELETE verb does? Right, so you have a resource at a particular URI, you want to delete it, make a request with the DELETE verb. Good, you're keeping up. Let's talk about status codes. Status codes are the headline news. They come back with the response from a server, and they tell you what happened. Typically, these are the most common ones. 200 means everything is okay. Most frameworks, CMSs, and other tools will emit a 200 by default. If I make a request to your API and there's something wrong and you send me an HTML error message and a 200 status code, that is the moment I will hunt you down and kill you. I integrate with a lot of other people's APIs. I'm just getting less and less tolerant as I get older. The 201 status is something that you will see in RESTful Services because we are posting a new resource representation to a collection and creating a record. You are going to see full-on examples of this soon, but it was quite code-y, so I thought we could do the story first, and then I would drown you with code. The created tells you that something was created. The 204 response is one that you do sometimes see, and it's literally 200, everything's cool, and I have intentionally sent you empty body content. This is used, for example, when you delete something. If you request the server to delete something, I did delete it. I have nothing to tell you. It's gone. It's not really a 200 because if you saw a 200 with a blank body, you might be confused, and we use 204 for that specific case. Anything beginning with a 2 is good news. Anything beginning with a 3 is yes, but there's something we need to talk about. The example here that I've given is 304 for not modified. You would use this with something like a last modified or an ETag header, where you've requested a resource, you've received the resource, it had some information about its version in it. Next time you request the resource, you send information about which version you have. If you have the current version, the server says 304, it doesn't need to send you anything else. You just use the version that you have. That saves repeat transmission of data that does not change often. Very, very useful for sites which need to scale. Anything beginning with a 4 means you did something wrong. The 400 bad request is kind of a nonspecific, I don't really know what's going on here. You probably sent bad data, or the server was stupid and didn't understand some combination of that. The 404 is specifically you asked me for a record that wasn't found. Literally you did a get request on something, and it doesn't exist, it is not there. Those are the common status codes, and there are many, many more. There's a fabulous Wikipedia page. If you want to lose the rest of the session reading about status codes, you should look it up right now. It has a very improbably large list of status codes. The things that you need to know are you should go there and you should use the right status code, even if it's as simple as 400 something went wrong, 200 everything's cool. That's a good start. There are status codes covering all kinds of things, from redirects to problems with you must authenticate, your authentication is invalid, this record doesn't exist anymore, this record was updated since you last used it, and so on. So there's lots that you can do there to make your APIs more informative to the user. The more information that you can give to whoever or whatever is consuming your API, the less likely they are to open support tickets, and the more likely you will make it to the pub. That's the aim of the game. Let's talk about HTTP headers. This is something which, because we don't see headers, when we are working with the browser, the browser handles that side of things and we really only see the body. As web developers, sometimes we don't pay quite enough attention to this aspect. So I have some example request headers. A lot of my code examples will look like this. If you are a long way back in this room, you probably can't read the code samples. In which case, feel free to download the slides. They're linked from the footer of launajane.net and they're also on the session page for this session on the conference website. If you make a general get request to launajane.net, this was made by Curl. I'm not going to do a big tangential rant about Curl, but if you'd like one, please see me in the bar later. We send some headers. In this case, we're just sending three headers. We're sending the user agent, which says what it was that made the request. This is totally unreliable. You can send any user agent you like by sending most of the tools. All of these headers are as trustable as get, post or cookie data, i.e., they are not. The host header saying which domain the request was made to and the accept header. This is a horrible example of an accept header and you'll find out why in a moment. Here are the response headers which come back if you hit launajane.net. You get some information about my web server, the Apache version, the PHP version, where you can ping back to, if you're linking to one of my wildly popular blog posts, some caching information, the content type. You've just made a request to a website and the content is in HTML. That's good and for rest, we'll start to look at things which are not HTML. When the body is not HTML, the content type shouldn't be either. Some dates there's a varnish header in there. I'm running WordPress, so I'm running varnish in front of it. We negotiate content format using those twin headers, their sisters really, a content type and an accept. When you make the request, you say I accept this format or this list of formats. This slide shows the example that my browser sends. This is a standard Chrome header and this is the accept header that a default Chrome installation sends, saying I understand HTML, XHTML and, well, XML and failing that. Star slash star. Whatever else you've got, I'll have that. That's why curl sends the star slash star. Curl does not understand every file format ever invented. It's just trying to get you to think that you can work with. To pass this accept header, you need to think of this header as a series of comma-separated values. Here's the header again. So we split the comma-separated value. We split this string on comma-separated values, which give us some types and some which have an extra Q thing in. The Q is a measure of preference. The default is 1 and anything less than 1 is less preferred. You can say I really want XHTML and if you have XML, okay, and as a fallback, okay plain text, but it's 0.5. You can not just send a list but also send information about really what you want and what you'll settle for. That's different things. In addition to accept, language, accept encoding and accept character set. So for different kinds of clients that will understand or want the content in different versions or different encodings, you can do things like this. Is everyone okay so far? That's good. This is the point at which I got really bored of telling you about all the wonderful HTTP textbook things. I wrote the textbook, I have some to give away and you can read that at your leisure. I'll show you some examples of how I really use these kinds of services. All of my examples use GitHub. Has anyone here used GitHub? That's quite a lot of hands. Good, well done. So GitHub have a really good API. It covers things we're familiar with because we're developers and they also have implemented quite a good restful platform. So that's why I really like it as an example. Here I'm making a get request to the collection of issues on my demo repo. I'm Lorna Jane on GitHub, feel free to click around so you can see this on the web. I make a get request, I send the user agent the host header and the accept header. Spot, there's an additional header in this request and it's an authorization header. GitHub uses something called OAuth where you negotiate with GitHub to acquire an authorization. That's an access token. So, authorization, name of token and then your access token here. You send this as a header. So we're not cluttering up our restful requests and responses with user names, passwords, who knows what else. Chucked in as query parameters or somewhere in the body. Rest clears that out of the way. This is the envelope format of HTTP to wrap that into a header. It's part of the request but it's the address on the outside of the envelope, not the birthday card that's on the inside. It separates our content from the negotiation and the metadata. So that's an OAuth header. It's worth getting into this if you're going to work with GitHub because they allow 60 requests per hour per IP so I'm running a workshop with that going on. You get like 1,500 an hour. Oh, you're going to get some headers with examples. So the response to my request for a collection of issues, this is the headers. I make the get request and the response comes back. The first line says 200 okay. We're doing something right, this is good news. We get some information about the server, the date, the content type. It's very important. If a response or a request actually has any body associated with it so when you're making a request a post request or a put request will have some body data it therefore needs a content header. Any response will usually have some body data it needs a content type header because otherwise how do you know how to unpack the body? This is really important. If I make a request to your API and my accept header says I want JSON if you send me JSON I still need a content type header but if you've sent me XML then I really need a content type header because if you have the wrong version of PHP it seg faults when you JSON decode nonsense. So we need to be really careful about sending the correct metadata. In this case GitHub is sending me JSON. GitHub actually only supports JSON. Sometimes that's acceptable. It depends on the application. Stata. There's sent me another status header. We've got some caching information. We've got a last modified and an ETag. We've got some Xoorth scopes. That's a GitHub specific thing saying what stuff I can do with my access token. I know it's GitHub specific because the header starts with an X dash. It is valid in HTTP to use any header you like. You can invent your own so long as the client and the server understand them. Occasionally things go wrong in between if you have deep packet inspection but in general in HTTP specification terms it's completely valid. However it's conventional to prefix your invented headers with X dash just so everybody knows that they are custom to your application. What else have I got in here? The last line is a content length which helps you know if you have correctly passed it and if it's all arrived and so that's a good one. We've made a get request. We've got the response. This was the headers. This is the body of the response. It's actually a really edited body of the response and even then I think the text size is still a bit small. This returns us the URL. This is how we identify this issue. It has a unique URL. We will be making requests to this with different verbs. There's a link to the comments URL. That's an associated collection so it's a collection of comments that relates to this URL and the resource includes information on how to get there. It's a hyper media. As you can see it's a bit like hyperlinks. Isn't nearly as complicated or trendy as probably it can be made to sound. A link to another place where you can find things. There is a title. It's broken and a body. This thing does not work representing a typical bug report. If you look at the user line you can see that I chopped a bunch of JSON out of here. Inside there was a whole representation of my user details on github which wouldn't fit on the screen but it meant that if you were showing a list of issues you could see who opened the issue. You could link to my account. It's got my avatar and so on. That's all included in the issue because you probably don't want to show the issue without showing additional information. Whether or not you include that information or link to it with some kind of hyper media is completely up to you. I'll pause to say something about hyper media. It literally is just hyperlinks. If you were doing a page that represented Drupalcon you might have some hyperlinks to the individual talks. If you're doing it in an API give me some hyper media to the talk resources or maybe a list, a collection of talks. It's exactly the same thing. The design of the user journey through an API or links is very much in a parallel to the way that we understand the way our web users use it. So whether it's another application that consumes your API whether it's your own mobile app with thinking about this design where would they need to go from here which data needs to be included. Using hyper media means that clients can navigate for themselves. They can grab the issue resource and follow the comments property use the value of that to find where the comments should be. As an API provider this means that once in a while you can break your URLs because people are not concatenating things together with IDs. I try never to return IDs like raw IDs from a RESTful API because it leads to people concatenating things together when actually all the links they need are here and if not I've missed something and they should tell me. Let's talk about a post request. This is a little bit more interesting than the get request because we get to send some data. This is a post request. I'm going to create an issue. No, I'm going to create a comment. The comment's really small and simple and fitted on my slide. So I'm going to put a new comment against the issue that you just saw. So I make a post request to the collection of where the comments go for this issue. I'm sending some headers post accept header content type. I'm sending a content type because I'm sending body data. If you send body data, please send a content type. There's my authorization token. Again, this is not a valid GitHub token, by the way, because I'm crazy but not that crazy. All my slides are in text-based markup so I make it all and then I do a finder replace and just scramble my key. Content length 37. On the last line, you can see the JSON that I sent. The only required field for a comment is the body of the comment. It knows who I am. I'm logged in. It's got my access token. All I need to do is stick some words in there and I can send it. I'm asking GitHub to create a comment. The response comes back. 201 created. That's good news. It's acknowledging that a new resource was made in response to my request. Content type, application JSON. Cool, so I know how to understand the body. What else have I got? A location header. A redirect header came back with my created acknowledgement. This is a redirect to the URL of the new comment resource. So it's very common to get a 201 and a redirect. So you post to the collection and you'll get redirected to the new record. It's quite an elegant way of doing things and it's very common. Content length, e-tag, cache control. Standard HTTP things. So the body contains the new comment. There's the URL of the new comment, the URL of the issue in the API that it relates to. I've chopped the URLs so that you would have some idea of what the more interesting end would look like. Again, I've chopped my user record but it's still in there so you can see who made this comment, linked through today's URL, their avatar, any other information that you want. Sometimes stamps and the body. So, so far so good. We have fetched data from GitHub and we have posted data to GitHub and REST is all about working with data. You already know how to work with databases and typically this is just it goes in your storage layer and in fact that actually some of this data is somewhere else over an HTTP request doesn't matter to most of your application request. We use put to update things and to use put first you must use get. So you do get, you fetch the record, make whatever change you need to do so that now you have a new representation and then put it and you put it back to the same URL think of tidying up your bedroom you get something, change it, put it back to the same URL with a put verb with your request. So you grab it, you get the JSON representation change the JSON representation put back to the original location and the response comes back with a 200 okay and it just sends us the new version of the resource because we're still on the same URL with the updated e tags and last modified and so on which would be lovely except GitHub don't actually use put. They're a really good example of a restful service but they don't implement put they implement patch. Now this is interesting, it's controversial actually and I'm going to explain it to you anyway good, excellent. GitHub use patch with incremental changes you know what a diff is and you get just the changes and you patch and you reply those small changes to the existing thing. This is the same thing in HTTP. Pure rest says you must only deal in whole representations there can be no data validation there can be no violation you must take the entity and put the entity in the real world that's not very useful so patch allows us to just change for example the email address on a very large user record you might not want to get the whole representation of an article to change the title or add a tag so patch lets us work around this and GitHub uses it so in the hope that I won't blind anyone with science here's the patch request all I'm going to do here is make a change by sending a new body to the comment that I just made so there's the URL of where the comment went user agent host accept header content type because I'm sending body authorisation because I need to be logged in as me to edit my own comments exactly as I would be on the website when I'm testing this I do it with GitHub open in my browser in the other window and I go oh yeah cool good and that's literally how this works if you have the mobile client for GitHub or like I use it on the tablet that's what it's using it's the API behind the scenes probably their website consumes it as well so I send just what I want to change in this case I'm just changing the wording of the comment I have improved my comment back comes the response 200 ok and that includes as the body the full representation of the new comment just for completeness I guess so that's patch just changing a single entry rather than having to collect change and then put back a whole record I quite like put patch is not widely supported but definitely part of rest conversations now so I really wanted to include it so that I could show you easy ok the delete request guess what it does you send the delete verb and name the thing that you want to delete again of course I have to send my authorization header because you can only delete my comment on GitHub if you're logged in as me and back comes the response 204 no content there's nothing to send me the resource is not there and I asked for it not to be there and it comes back 204 no content and that's a 200 but deliberately content length 0 if you are working with github be aware that if you are ever sending post put or patch with empty body for some reason starring repose works like this you do need to send the content length of 0 gone through examples of all the four and of it verbs four verbs I would have liked to have used and patch because github uses it and it's an important topic in rest I want to talk a bit more now about making the most of HTTP and about some of the allied architecture decisions that you will see and I think these apply whether you are implementing and publishing your own restful service or whether you just want to integrate with something which already publishes data over rest you saw the authorization header it's a very tidy way of exchanging identity credentials when working with a restful service because all of the details are in the header you have a couple of options you can use basic auth if you want to this is a very mature well understood well supported platform you already know how it works why not apply it to your API as a web developer you have most of the skills you already need to work with APIs all of them different kinds of APIs so use the basic auth actually probably use digest same thing but encrypted passing things in the headers using tokens why would I use a token over using your actual user credentials well it's because lots of things are now logging into Twitter, GitHub, Flickr as me most of them are on my phone some of them are clients on a tablet they might be exchanging data when I post a Flickr for example the photos appear on Facebook there are lots and lots of things accessing my accounts using a token means that if I don't want just that to have access anymore I can revoke one token every single integration point has its own token so whether you follow a formal process such as OAuth or whether you are rolling your own tokens it's a very good way of revoking access for something without the user having to change their credentials and then update every other thing that uses it so a very very sound approach I could talk for an hour about OAuth and again I'm going to try not to but find me in the bar on OAuth in 30 seconds why did I think this was a good idea there is so much I want to tell you about OAuth OAuth handles the relationship between you something which has your data and something else that you'd like to have some potentially limited access to your data if you give your username and password to your Flickr mobile phone app then that app perhaps might use your credentials to log into Flickr impersonating you OAuth gets around that and sort of deals with the fact that there are three players there's you, there's Flickr and then there's the app and you kind of all get together and you say you say to Flickr okay I'd really like you to grant some access please to my data for this app when the app accesses Flickr Flickr knows it's the app and not you that access might be restricted in scope it might be read only Twitter does read only it might be limited for time it might only be valid for a month or however long it takes if you decide that the app that you downloaded from who knows where turns out not to be all that reputable and it's polluting your Twitter stream you can revoke the token without necessarily having to revoke your users access or any other access to that same provider so that's what OAuth is for is for giving something else access to your data that lives on a particular provider you'll see a lot about OAuth OAuth 1 should not be touched with a barge poll OAuth 2 finally made it into a real spec that bears no resemblance to the way that people actually implement it but OAuth 2 is really, really good all you need to know is that you will generate tokens and you will use SSL so do OAuth 2 do it over HTTPS good implementation that was much quicker than telling the whole story okay, let's talk about caching headers you already know a lot about caching headers because you cache assets on websites basically the same things apply it's very important to get caching correct because when your mobile app goes in the top 10 for your code when your mobile app goes in the top 10 for your country then your back end is going to fall over caching headers will help you to make the most of your hardware and reduce the load for everybody the expires header gives the client information about how long it can keep a particular piece of content we use ETag or last modified to check that something's changed so you saw the example with the 304 header when I make a request and I retrieve some content it comes with an ETag or a last modified date when I request the same endpoint the same URI in the future I send as a header the if modified since or the ETag if it hasn't changed the server just sends me a 304 that's very, very quick using REST over something like RPC all post requests means that things like the reverse proxy caches barnish and so on can help you in terms of caching because if it's just a get request and all of the responses will be the same then you can cache it a post request can't be cached because it's not a safe operation so REST recognises that get is always safe and we can probably cache that I mentioned right at the start that I run varnish in front of my WordPress installation there's no personalisation on my site the only person who can log in is me so when I write a blog post quite often I do see a spike of traffic varnish can just handle that for me everybody's seeing exactly the same thing don't need to wait for WordPress to do its thing and generate some output we'll just cache it and send it the other advantage of the caching headers I'm not sure how I got into a varnish tangent but the other advantage of the caching headers is that it allows us to detect changes in version when we are trying to do an update you can clearly see that this get change things put is not atomic the caching headers help us with that so when we send the put we can send what our last modified timestamp was or we can send our e-tag the server can then make a decision about whether our version can overwrite or not and there's a 409 conflict status code which would say generally no I don't think that's a good idea for the most of the time it's fine but it would allow us if your application needs to know that there was a race condition we can detect it and that's an additional side effect of these caching headers I want to talk in general about restful services just as I kind of wrap up this talk I want to try and place them in the wider world of the web and of mobile when to use rest there's two provisos here rest lends itself very well to data driven applications so if you are mostly working with data I work on an open source project called joined in it is a list of events the events have talks and the talks all have feedback have comments on them you can kind of imagine that this database has about five tables in it right it's really really data driven so it lends itself very well to a restful model because it's just representing data your sort of products and orders and that kind of thing again small things if you have very batch driven functional sort of I'm trying not to say paradigm functional paradigm kind of applications then rest is less of a good selection so the other limiting factor for when you can choose rest is when it is understood or could be understood rest is not widely used in every aspect of the web community yet I would say more so for mobile less so perhaps for traditional web and if you are building a rest API to integrate with somebody else particularly if they are Java or .NET developers they may not be able to understand rest so the tool support is less good they like soap because there's a button and then the thing does a thing right this is a really scientific explanation of the problems with integrating with other communities within web scripting languages and the mobile space you will find rest is well supported and you will find rest is well supported Drupal obviously going way more in that direction moving forward but that can sometimes be a limiting choice I'm a consultant I'm an expert on rest I work with lots and lots of people and sometimes they build RPC services so it's about trying to understand the problem and make the best recommendations that you can if you are going to design a restful service then these are my parting tips try to remember that we are modelling everything in terms of resources everything is a resource every operation you dictate which one is happening by using a verb and all of the metadata which is not part of the resource gets sent in the header if you have a verb in your URL you are doing it wrong when you are designing any kind of service please consider the failure case to API providers users look like idiots they are not I promise they just haven't read the instructions so consider what happens when things go wrong the measure of how good your service is is how it treats someone when they have done the wrong thing that's a measure of robustness of reliability and again keeps the support tickets down and you can go to the pub you'll have decisions to make about how much data to return are you going to return every field available to be associated with this resource because when you do a list of articles or products or whatever it is that's going to be a lot of data or are you going to offer a more abbreviated format with the option perhaps as a sub resource or by passing a query parameter to get more data sometimes you might choose to send less data making more available somewhere else a good example is blog articles because all of the fields are small apart from the body which is humongous you don't want that when you're returning a collection you might even publish it as a separate sub resource sometimes you'll want to do the exact opposite and pull some related resource into your current representation and the example is the issues and the comments with the user resource nested inside it that we saw for GitHub you never want to display an issue without saying who logged it or a comment without saying who made this comment so you'll always want to nest that data even though they're probably stored in different database tables so those are the kinds of decisions that you will want to make when you come to publish your own APIs I'm hoping that this is giving you an overview whether you will be publishing your own or whether you'll be integrating with restful services elsewhere on the web of what's going on and why it's done the way it is what are we trying to achieve with these new and unfamiliar verbs what's with the pretty URLs so hopefully I've given you some overview at that point now I do have 15 minutes left I am going to take questions the first two that I take will get a copy of the book the microphone is there run excuse me what happens if you put an incomplete object does it delete the fields or the values that it does not contain or does it save them in the system or does that depend entirely on your API okay when you put an incomplete record what should happen depends on your application I mean in true restful terms it should reject it because it's a bad representation if they're optional fields you probably would write some business logic that just works skipped over them you decide if you want to null them technically I think you should probably null them but cool, come here and get a book next question I'm a little confused on the jargon just because I work with a lot of other developers that are a lot smarter than me or I guess more knowledgeable on this one of the developers I worked with the other day said I've never built a rest API before but I've built a restful one and based on your presentation I'm trying to think that's the same thing I think it's the same thing but I'd like to give you some advice when you're publishing a restful API you should always advertise it as an HTTP web service and that way the religious zealots won't hunt you down and kill you come and get a book yeah I made an application using Angular and it actually put out a request for XML and I had acceptance criteria where I wanted to get back application XML and I write that was the correct way to do it and we had issues delivering it where it was actually put on an IAS server which would return a text XML return it can't help you with IAS like there's two schools of thought I consider application XML to be the correct way to represent it if IAS thinks it's text XML then you probably just need to pander to that it's whatever works sorry more questions, yay good question how is a good approach for handling relationships let's say we have people related to workplaces is it a good or a bad practice to include all the workplaces in the return for a person this is a really good question and it's about publishing or do you just want to make it available and if you would normally want to see the list of workplaces every time you retrieve that user record then nest them by all means if typically you might want to and you might not I would recommend that you publish a collection as like a sub resource to that person record so if every time you requested the person you would have to request the workplaces collection that adds quite a lot of overhead especially for a mobile client because the connection overhead can be horrible if you're on a slow connection so then I would nest it if you sometimes need it and sometimes don't I probably would try and keep them separate I think I said it depends but thanks more questions why don't you need to perform a get request first when you perform a patch you don't need to perform a get request when you perform a patch well I guess you probably do need to know which fields are there but you know which record you need to update you need to do it really for a put so that you've got a representation to edit whereas with a patch you're just sending a thing so you don't need the template of the previous version I was delighted to see your examples with the github API because I was just working with it in the last two weeks and I have a question about selecting libraries and whether you have a service do you choose a PHP library like one of the ones that github recommends or features and if so any tips on evaluating libraries or maybe you just interact send your own request I do everything from curl right it depends usually what the application I'm building it into is so some of the frameworks have very good support for restful APIs sometimes it's worth pulling in one of the wrapper libraries like you say github has user contributed PHP libraries typically if I have the choice I'll use the Pekal HTTP extension in PHP it's fast it's easy to use it's well supported that's fairly rare I guess not many of you use Pekal but there's a cool client called guzzle as well which might help to evaluate I literally set a tiny task and three things I want to try and try and do all three in an afternoon and the one that makes me swear the least I'll give a presentation I would like to talk about semantics so in your example we have on github and comments of the issue so when we want to see all comments of the issue X we call issue slash X slash comments right and we get the list of the comments with IDs so I want then to get the full object of the comment ID so I will call issue slash X slash comment slash Y right but how it conforms with the thing that it's sub resource but then I can provide also resource that will be just slash comment slash Y okay so what you would normally see is under issues slash X slash comments it's a collection and the resources will each have their own URI or URL field which just goes to slash comments slash Y so those individual resources would normally but they do belong belong under slash comments but they also belong under slash issue slash X slash comments but when you see the list of resources I wonder if I have it when you see the list of resources then you will see each one of them contains this URL field which is the first in this example and that is where you will find the comment at that URL do you want to answer your question? yes so as I understand I will need to implement still slash comment slash Y and then in URL I usually don't slash comments returns this so the resource which is a comment appears in multiple collections because it's applicable to multiple collections okay thank you I want to say this is one of the best sessions I've attended all week then excellent thank you if you'd all like to leave that comment on my feedback lovely so github has this custom verb patch so it will allow custom verbs to be created I've worked with SOAP where you can get a whistle back telling you what you can do on the server how can you find out what verbs are available on a rest? no you can't rest will have a company in documentation patch technically is a custom verb because it's not part of a spec but it's widely used by lots of different APIs to perform exactly this sort of diff patch thing rest doesn't come with a whistle or equivalent what you will get is usually good hyper media from some kind of starting point and usually good documentation often interactive did that answer your question? so you have to request the documentation you can't if you have a look at github's docs it's actually quite good there isn't a machine discoverable documentation if you are interested in this stuff look up something called HAL which is a standardized way of adding hyper media in so that things can spider your start from a point and find all the related resources and collections and sort of find their way around I typically find that most clients need a custom implementation anyway it's like not knowing what the database tables are called you guess hopefully that helps ok thank you my pleasure I just have a couple questions when is it appropriate to use query string parameters in your URL versus like a resource support slash that's a really good question when is it appropriate to use query parameters when you are making a get request and those parameters are separate from the resource identifier so we are going to have issue slash 42 and anything extra like you want the most representation of this resource or sometimes people support the format as well as a query parameter instead of just the accept because not everyone understands how to use accept not all clients like javascript libraries know how to use accept so anything which is extra information specific to the resource or collection so it's not really metadata specific to the resource or collection but don't do issues 42 slash verbose slash yes slash the other dot xml right those things go somewhere else did that answer the question yes the other question I had was all these examples are obviously focusing on string based or textual based data going back and forth what about binary situations is there anything REST can do there or do you need to I mean yes there's no reason why you shouldn't do example images this way because we're not version controlling them we're saying please give me a representation of a resource there's no reason why that shouldn't be jpeg please accept this representation of a resource no reason why that shouldn't be jpeg so the same principles would apply if you want to work that way thank you my pleasure wow am I done I like it when this happens cool excellent so I am going to say thank you very much this is the book that I was moving away PHP web services is my newest book so I'm still like super excited because I have an O'Reilly animal book I came here a year ago not quite to Oskong met the O'Reilly people told them I wanted to write this book I'm back in Portland and I'm holding it in my hands this is the place where magic is made so that's it please leave me some feedback I am completely new to Drupalcon and it's been amazing and if you would like to get in touch with me I do a lot of API consultancy and training or if you just want to send me an email whatever that would be lovely my details are there thank you so much for your time