 Okay, I think we're going to get started because we have a lot to talk about, but there will still be some people trickling in from lunch, I'm sure. So we're here to talk about REST and serialization in Drupal 8. I'm Lynn Clark. I'm a core module maintainer for the serialization module, also the HAL module, which I'll be talking about in this presentation, and another module or two. And I recently joined the Tag1 consulting team of top-notch performance engineers. And this is Klaus, Klaus-Pierre. He is a developer at EPICO and has been working on REST since Drupal 7. He did the REST-WS module and has brought a lot of those principles to Drupal 8 with the REST module. Okay, also, just want to give a heads-up, we are getting into some details of how things are implemented in Drupal 8, which means that there's actually a lot of code in these slides. If you're interested in those details, you might want to move forward, although this is a pretty large screen, so maybe that's not a problem. But there's also, these slides are available on the web. They're updated each time we give this presentation with any API changes or anything that's happened since last time we gave it. So you can go there to see the slides at any time. So first, I want to talk a little bit about what REST is. People are super excited about REST and Drupal 8. It has been talked about a lot, but I'm not sure that everyone's on the same page as to what REST actually is. So I want to just give a basic intro to just make sure that we all are on the same page or using the same definitions. So I'm first going to start with some really boring, dry Wikipedia definitions. Wikipedia says web services, a web service is a method of communication between two electronic devices over the worldwide web. So that's a really boring way of saying it's what you do every single day when you're using the web. You know, say that you're using your phone to get maps, because you're at Drupal con and you have no idea where you're going. So your phone in this case is a client to a server like the OpenStreetMaps server. And you're sending requests, you're communicating with that server. You're saying, you know, get Portland map data or get Prague map data. Or you're saying add a new road to this data because OpenStreetMaps is actually both read and write capable. So that's what a web service is. You're actually pretty familiar with it, I'm sure. And Wikipedia says REST is a style of software architecture for distributed systems such as the World Wide Web. So that's basically saying it's one way of doing web services. There are actually other ways of doing web services. You may have heard of SOAP, XMLRPC. And so it's important to know that RESTful web services is just one style and to know the differences between. There are some key differences that it's important to know between these different styles of web services. And they mentioned the World Wide Web here. That's because the guy who came up with REST as a way of describing software architecture, he was actually one of the people who worked on HTTP. So he was working on HTTP, took a step back to rate his thesis and kind of generalized the ideas from that early web development and generalized them into a general architecture. So I'm just going to show what we have in Drupal 8 right now. You could test this on your own. This is the most basic REST request you could use to interact with Drupal's web services. So first we go to entity node one and we run a get request. I'm using a browser extension called Dev HTTP Client. You can get this for Chrome or other browsers. And there are other ones that you can use it with all. So you enter the URI here. You say that you want to get that resource. And then you add an accept header. So you're going to accept application JSON. And then you get back the node in JSON. So let's go over the four basic components of this really simple request. There's the base format, the HTTP verbs, the URI, and the media type, also sometimes known as the MIME type. So the base format, I'm sure you're all familiar with base formats. For example, JSON is an example of a base format. XML is another example. It's basically just the way that you take information and put it into a string that can be sent along the network. URIs are used in two ways in REST services. So you use URIs to indicate resources that you're interacting with. These are the things that you want to modify or create. So in Drupal 8 right now, if you were interacting with node 1 as your resource, you would have entity slash node slash 1 as your resource URI. We hope to change that. Clouds can give an update on where that is. But we want it to actually be the same URI that you interact with when you're interacting with the HTML page for that resource. And then another way that you use URIs is link relations. And that's basically the way that these resources are related to each other. So for example, you might have a link relation between a node and the taxonomy terms that it is tagged with. So that would be one example of a link relation. I'll get into link relations more towards the end of this talk. But I want to give an example of the restful use of URIs and contrast that with what is not restful. So what's not restful is if you post to an endpoint and you have your identifier actually in your body, in the content body, so that you say you wanted to interact with node 3, you would have your identifier in the actual body. Instead, what is restful is to actually post directly to the resource URI for node 3, or thing 3. So media types. People often get media types confused with base formats. One of the reasons for this, people think that JSON is a media type, which it actually is. It is a media type. But in addition, you can have more specific media types that build on base formats. So HAL is one that we're using in Drupal 8. And all that HAL does, saying that you're using application HAL plus JSON, all that does is indicate that there are a couple of extra bits of semantics. The consumer knows that there might be this links keyword, or there might be this embedded keyword that they can use to get some extra information. And so it's really just a contract between the client and the server as to what the extra information contained inside might be. So you can have these media types that are specified on top of base formats. These will often go through standardization bodies, such as the IETF, W3C. Or you can even have vendor-specific media types. So GitHub has their own media type. And there are special rules. They say all resources may have one or more wildcard underscore URL properties linking to other resources. Now, I think it's actually a lot nicer just to have the links and embedded keywords rather than having to do a regex on keys. But any consumer that actually understands the GitHub media type will know that they have to regex the keys and will know how to do that. And so some of the people who are into pragmatic rest will say that to indicate your media type, you should just append the file extension to the end. But that gets a little bit messy when you start using these more specific media types when you're not just using base formats. And so instead, a restful way to do it is to use the HTTP headers that are actually meant to communicate this information. So you have the accept header, which you use when you're doing a GET request. Basically, you can specify what things you accept, what formats you accept and understand. And then if you're actually sending some data up to a server, use the content type because you know what the media type that you wrote that in is. HTTP methods, these are how you indicate how you want to interact with your resource, what you want to do. So for example, we have implemented four of the standardized. Well, one is not quite standardized, but we've implemented four HTTP methods in Drupal. So the first one is GET. And what GET basically means is go fetch this page and bring it back to me. Don't change it. It's important to implement GET in a way where if somebody sends a GET request to your site, you aren't actually changing things. You aren't actually deleting nodes or doing anything like that. Post doesn't have quite as strict semantics as GET, but most people use it in the same way. Here's some data. Go make a thing for me. Basically, you're creating something new. Patch is what we're using in Drupal to say here are some change fields. Go update them on the existing thing. Another HTTP verb you can use to indicate that is put, but we, for very specific reasons, have chosen to use patch instead. We may remember to talk about that later. If we don't remember to talk about it, feel free to ask about that at the end if you're interested. And then delete, you know, get rid of that thing. Pretty simple. And so a non-restful way to indicate what you want to do is to actually have your verb in the URL to say, you know, you want to get node one or you want to add a node. Instead, you should use the HTTP methods to indicate what interaction you want to have with this resource. So let's look at how these four basic components came together for that really basic request that we did earlier. So we had the base format, which is JSON. We had the URI, which is entity node one. We had the HTTP method, which is get, and the media type, which is application JSON. So let's just change a couple of those things. We're going to change the URI that we're interacting with, the HTTP method to post, and the media type to application how plus JSON. And so if we go through this, change our URI, our HTTP verb, we're using the content type header here instead of the accept because we're posting. And then we run that request. You'll see that there's a 201 created that shows up here. That's a status code. It's a way of communicating from the server back to the client what happened. When you sent this request, this data up there, what happened on the other end? So 201 created is a good thing if you're posting. That means it was successful. And if we go back up here, you'll see there's a CSRF token that I had to send here. That's because I'm using cookie off, which is what you use when you're just interacting with a Drupal site usually. But we also have, since I did this demonstration, we have implemented HTTP basic auth, which Klaus will be talking about more later on. And so I think that most people, they see these two interactions, and they think, OK, we're done. Rest in Drupal is complete. It's finished. But if you actually look at Roy Fielding's thesis, the guy who came up with rest, and if you look at his writings since then, it's clear that what Heeman, when he was talking about rest, included more than just using HTTP verbs, using resources. And so this guy, Leonard Richardson, came up with a really simple model of examining the restfulness, how closely an API is aligned with actual rest. And so level zero is the swamp of POX, the swamp of plain old XML. That's where you're sending your identifiers for the resources you want to interact with as part of the message body. It's where you're interacting with just one end point URI. And so level one is when you actually start breaking those out into different resources. You don't have a single endpoint anymore, but you actually have individual resources that you're interacting with. Level two is when you start using the HTTP verbs to interact with them. So instead of tunneling everything you want to do through posts, so like posting that you want to delete something, you actually start using delete in the way that it's meant to be used. So we have a pretty solid, we're at level two. Level three is hypermedia controls. That's a bit trickier, and that's where a lot of restful web services are not actually rest in the sense that Roy Fielding meant it. So I'll be talking about hypermedia controls later in the talk, but right now Klaus will show you what we have implemented right now to get to level two. OK. Hello from me. So I'm going to talk about a bit the concrete implementation of the restful web services module in Drupal 8 and how we implement those standards and what we were thinking when we were doing that. So at first I want to take a step back and take a look at the big picture. What are we actually trying to do? And what I'm talking about here is getting stuff programmatically out of and into Drupal. So of course, Drupal delivers HTML pages to humans, but since web services are about interacting between machines, we need to do that in a format that has no styling attached to it or is not meant for visual representation, but to represent the actual data in a format that can be easily transferred and processed for other purposes. And in this context, Drupal acts as a web service provider. So what we are talking about today is that Drupal is the data hub where you can post data to and get data out of it. So I'm not talking about the client side of web services. I'm not talking about interacting with Facebook or Twitter or other web services that are out there. But Drupal is a provider of that data and how you can pull that out to your phone app or whatever. And as I said, we need to have a machine readable format that is used to exchange that information between programs or machines. So what use cases do we have in Drupal? I put a picture of the phone up here because that's the most obvious reason people are quoting nowadays is that we have native apps on a phone and that want to fetch a couple of notes, for example, from Drupal. And they can do that with that RESTful interface. Or we can have some on-site JavaScript that interacts with the server in the background without reloading the page, loading some additional data in a sort of HX fashion that can all be done via that RESTful web service interface. And you can also think of it as a use case as a public REST API. So you're providing some service on the internet and to want to give other third party companies a chance to integrate with a service. So you would provide your own data via a web service interface and they can do that with the RESTful web services module. And there are a couple of other things that you can do, for example, migrating stuff. A lot of people know the migrate module where you can import data into your Drupal site. Now you can also use it to, if you're not having access to the database of the Drupal site, you can write to that site. So you have to use another interface, maybe for security reasons, that's where you would use the RESTful web services interface. And also, for example, deploying content from a staging site to the live site with just a click of a button the data is transferred to another Drupal site. That would also be a use case. And if you look a little back in the history of Drupal and how we got here to the RESTful web services in Drupal 8, we can see that there was the services module. That was the approach in Drupal 6 and in Drupal 7 to expose stuff. And it has a procedural way to deal with data. So it's not resource-based, as in the REST principle, where you're exchanging resources. But it's more like a remote procedure call approach. And it also supports that fashion of interacting with web services like SOAP. And yeah, it does a couple of things that are not so nice. For example, using Drupal form submit to actually store the data, which has some side effects that usually are only expected to be run in user interface and not when machines interact with the website. So that has some drawbacks that we want to get rid of. And also, it's hard-coded to specific entity types like nodes and commands and users. And if you have an additional entity type like a commerce product, it doesn't work you have to write a specific integration. It has some explicit authentication hooks, so it doesn't use the Drupal user authentication system but at its own on top of it. And of course, it also has no hyper-media controls. The highest level, Lin was just talking about where we actually want to get to in the Richardson maturity model. And there are a couple of new approaches in Drupal 7 Contribute, which is the REST WS module and the Services Entity API module. So what those modules are doing, they're using the Entity API Contributed module in Drupal 7, which has metadata about entities. Actually, it provides metadata about entities. So we can use that to inspect all the different entity types on your site to expose them in a RESTful web services fashion. And yeah, the REST WS module, for example, tries to follow the REST principles as far as it can get on Drupal 7. So it also has some drawbacks, like, for example, using slash node slash one dot chasing, which Lin already said is not a best practice, but unfortunately, the routing system in Drupal 7 is limited. So we have to do it in that way to not get any security issues with page caching, for example. Yeah, you can look that up. It's just a minor detail, but I wanted to mention it here. And of course, in Drupal 8, that changes because we have a new routing system that is a lot more powerful, is better tested. It is a component that we use from Symfony, so we can implement that in a better fashion. But if you're on Drupal 7, and you look into that, you should consider those three modules, services, REST WS, or services entity, that could serve your purpose. And now how we arrived in Drupal 8 Core was to basically reinventing the REST WS module that I wrote in Drupal 7 and expanding it to the concepts of Drupal 8. So there's the REST module, there's the serialization module, there's the HAL module, and there is the basic authentication modules, for more or less interconnected web services module in Drupal 8 Core that you can use to provide web services on your site. So just that you know what you have to enable on a Drupal site, there is a patch already that creates a web services package to group those modules together. So I think that will land in the next days, and then it's more clear what you can use in Drupal 8 Core for web services. And just to be clear about resources and operation and how we use them, the resource in the REST for principles is the object of interest. That's what we want to manipulate, that's what we want to fetch, that's what we want to work with. And we mapped that to the Drupal 8 entity system. So we declare resources for entities, the node resource, for example. And an operation is the action to interact with that resource. For example, if we create an operation where we create a new node, we use a POST request for that, and the path would be slash entity slash node. And the same applies to read and update on delete, that are the four most basic operations that we use. You basically don't need more, that's all you need to work with your entities, your resources in Drupal 8. And as you can see, we're still using the slash entity slash node path, although Drupal uses slash node slash 140 HTML output for humans. And we're trying to fix that to have the RESTful path where you can get JSON or XML or the hell serialization format also on the slash node slash one path so that that is unified. The patch is not ready yet, so that might change. I'm not sure whether we leave the slash entity slash node paths intact, but just that you know that that might change in the next couple of months. And by exposing these entities, we are implementing resource plugins. So Drupal 8 has this new fancy plugin system, which we are also using for the REST module. And we're implementing it with the new entity API and metadata that we know about the fields. It's basically the same as we already did in Drupal 7, but the metadata stuff works far better than in Drupal 7. And so we know all the properties and all the fields an entity has. So we know what we have to output regardless of the entity type. And we wrap that in a plugin so contributed modules can write their own plugins if they don't want to deal with entities, but in core, the heart of the RESTful web service module is to implement it for entities and make that work. And yeah, I see Lynn looking at the iPad. If you have any questions during this talk, use the hashtag hash rest hash Drupal. If you only use hash rest alone, that might not be clear. So please add hash Drupal at the end and we will take notes of the questions and answer them at the end. Yeah, there's also access involved. Of course, we have node access in core and field access. So that is as well respected in the implementation of those resource plugins. For example, if you fetching a node and you don't have access to that field, that field is hidden so you won't see it if you get the JSON representation of the node. While I'm at access, we have authentication providers in Drupal 8 core. So how are we doing access control? Basically, we have cookie authentication and HDB basic authentication in core. And that is not handled by REST module itself because it happens on an earlier layer in the Drupal 8 page handling phase. And yeah, as I said, we have the authentication provider interface in Drupal core that is implemented for basic authentication, which is a separate module now and for a session authentication, of course. And yeah, the problem is if you use cookies to authenticate your requests, you have to deal with CSRF tokens. So I would recommend if you're playing around with the REST for web services API, enable the HDB basic off module that is far easier to deal with and I will show you code examples about that. Yeah, we use extra user permissions for consumers to be able to access resources. So you have fine grained access who is able to post JSON nodes and who is not able to. Yeah, I think that's basically it. So now let's take a look at that, how we configure this for real on the Drupal 8 site as of the development snapshot that we have right now. I think Alpha 3 is the most recent release and REST module is already usable in that version but I recommend to just use the most recent Drupal 8 dev snapshot. So you basically just need a Drupal 8 installation. I put some drush commands up here in case you're using drush, it's really a useful tool so that you just see what you basically need on the site. As I said, you need to enable a couple of module, the serialization module, the REST for web services module and the HAL module and we are working with basic authentication so you also need the HDB basic authentication module which you can also enable with drush. That's what you need on the code side. Then you need to do a little bit of configuration. So we're using the new CMI system in Drupal 8 core and we have the active configuration directory which we just copied to the staging configuration directory and then we edit the config file, the REST.settings.yaml config file which is responsible to enable those entity resources. And so what we're defining here is I want to have the node entity exposed and I wanted to have exposed for get request and the supported formats I want to deliver is held JSON in this case, nothing else. And for authentication, I would like to use the HDB basic authentication module so that the format of the config file is not really complex. There's also documentation already on Drupal.org and with that example, you're basically done configuring that plugin. Then you sync the configuration, you can do it in Drupal 8 UI back to the active configuration directory. So you don't copy it back but you push a button in the UI to accomplish that. And at the end, you clear the caches so the routes get active and Drupal knows about the configuration and then that is set up. Then you need to configure permissions because by default, all resources are protected. So what we are going to do here is just give the anonymous user role the ability to read nodes on the side. Not read any nodes because node access and field access still applies on top of that but just to allow them to access nodes in Hellchaser, for example, at all, that permission is necessary. Yeah, you can also use a drush command for that. I added it here for the sake of completeness. And yeah, in order that we get the node, we create the node first through the usual Drupal administrative interface. So you have the node on the side, you have to prepare that. Then you can make a request to retrieve it. So here's an example how you would do it from curve, from the command line. And the important bit here is to set the media type correctly, the accept header. We want to fetch Hellchaser because nothing else is enabled. So we have to specify that. We specify the method, which is a get request and we specify the path. In this example, Drupal8.localhost is the Drupal installation on my local machine. Have to exchange that with whatever you're using or with your live site and going to entity slash node slash one, you can retrieve the Hellchaser representation. Or you can also do it from PHP. Curl is a very common library to fetch that. Basically the same, you specify all the headers that you need, the format and the path and the method. And you get the data back. You can just use the usual JSON decode function to get it into an array structure and then you can work with that data. Whatever you want to do with it. That's the way how you consume a node from some third party library or whatever you want to consume it. We also have introduced the Gussel library in Drupal8. So that's a little bit easier to use and a little bit more object oriented and it throws exceptions if something goes wrong. So I would recommend to take a look at Gussel if you're developing new stuff for Drupal8, which is also included in Drupal8 course. So if you're not getting the library with Composer, for example, you can also, if you're in a Drupal environment, use it from Drupal. The HTTP client service provides that for you. So you have Gussel built into Drupal. And same thing here, just prepare your request at the appropriate headers, execute it and there's even, you can even chase and decode it automatically with Gussel and then you have your array structure of the response. And what does that look like? That's just a small part of the response. So you have all the node properties that we know, the node ID, the title, fields, and you have the values in there. So the structure is pretty simple and pretty obvious where you can get your data. And so in the case where you don't want to fetch a single node, but a list of nodes, we decided to not implement any specific logic for that ourselves, but leverage the views module. Because what is views? Views is obviously a query builder. And we have a lot of infrastructure for that already. People can configure that in a very fine grained fashion. So we decided to just write a display plugin for views that exposes your rows that you fetch from the database in a held JSON format. And it's comparable to the views data source from Drupal 7 Contrib that we already know. And you can either decide if you output the whole entity for each row or if you just output specific fields. And that's basically it. That's how you do collections. That's how you provide lists of nodes or other entities as rest for web services in Drupal 8. So that was the reading side of things. Of course, you might also want to manipulate data on Drupal sites. That's why I have an example here about posting stuff to your Drupal 8 site. And I'm going to show you how you can write a new node to your Drupal 8 site. So again, we copy all the stuff of the active configuration directory to the staging directory where we are going to edit the rest.settings.yaml file. And we're adding a pretty similar entry for a post that we already have for get. And we want to use held JSON for authentication for supported formats and HTTP basic authentication. In this case, it's important because we will not give that permission to the anonymous user because we don't want anonymous users to create nodes, but to some specific user accounts, user roles that should be able to create new nodes. And yeah, in this example, we can give it just to the administrative user role. And in the end, we also have to clear caches so that the new configuration is picked up and everything is ready. And if you look at that example, you can also do it from the command line. It's a bit longer. So you have to make sure that the post body that you are sending to Drupal is correctly formatted as JSON. And the most basic things that you need to create a new node is you have to specify what node type it is. And that is done in the special links session in hell. And in this example, I also provide a title for the new node. And then I have to specify the correct headers. I want to do a post request. So I specify that I use basic authentication. That's why I have the user option here with the clause. He is the username and secret is the password. I also have to specify the content type what I am sending to Drupal in order so that it's know how to deserialize it and save it. And in this case, it's, again, application slash hell JSON. And that's basically it. Same thing with PHP curl from your PHP model or from your other PHP application that should talk to Drupal. You prepare your node array in this case. JSON encoded, initialize your curl handle, specify all the headers, path, method, the post data that you're going to send, which authentication provider you're going to use, specify your credential, clause and secret, and then execute your query request. And that will send your JSON encoded node data to Drupal. It will accept it, try to parse it, try to save it. And if everything goes well, you get a success status message back with 201, then you know everything went OK. Similar with Gussle, it even looks a little bit better than with just straight curl. It has a nice API to set the authentication, for example. That's basically it. Not a lot different. I'm just invoking the send method in the end. And Gussle takes that, gives it to curl, and that does the page request. So now let's take a look at resource plugins. I already said we are doing that in Drupal 8 Core for entities. But you might come up with a different use case that you want to implement in Drupal 8 Contrib. You don't want it to do for entities, but maybe you want to do it for some specific business use case that you have. And I'm just going to show you briefly how such a resource plugin looks like. So what we are doing is, if you're writing a resource plugin, you don't deal at all with serializations. We keep that out of the resource plugins because the plugins are only responsible to load data or save data. They prepare the data, hand it off to the serialization component, and it takes care to render it in the format that is expected or enabled. And we have only one entity plugin for all entity types in Drupal Core or Contrib. Whatever entity types are defined. And because of that metadata that we have about entities, we know how to render them and how to display them and how to turn them into Hell Jason, for example. As I said, contributed models can easily add their plugins. And yeah, one important thing about those plugins that they implement that are just classes. Plugins in Drupal 8 are just a standard PHP class. Most of the time, it will extend some plugin-based class. And then you implement a couple of methods on it. And basically, that's it. So in this example, I have the database log resource plugin example. And what it does, it just fetches watch.log entry from your log table and handles that to the serializer, which will return it in whatever format you want it to do. So we're using annotations here. I'm saying that this plugin is the dblog plugin. And I define the class, extend some resource base. And now if we look at the requests and what it corresponds to in the plugin, for example, for a GET request, we implement the GET method. We want to support GET methods. OK, we implement that, take the ID argument, and then do our query and return those results. Similarly, if we look at the path, per default, the plugin ID is used in the path. So of course, you can override that. Maybe you want to have that in some different path. But in this example, if there is nothing specified, it just takes the plugin ID in the path. So this is reachable under slash dblog slash 1. And the ID, this is the last part of the path because we want to identify which watch.log entry we want to load and return. And that is passed into the resource plugin. That is also passed down to the database layer. This is the record we want to fetch. This is then encapsulated in a resource response, which is also a class that we use from the symphony framework. So this is really an advantage in Drupal 8. We don't have to invent everything ourselves. We don't have to invent any response class. We can just use the existing stuff that is tested and that is work from symphony so that it's a huge relief. It makes our whole code base that we have in Drupal 8 a lot shorter. And then it's basically the response. In this case, we don't have any special serializer defined for the health format. So it just falls back to output it as JSON. Of course, you can override those serializer components to make a format that better suits your need or whatever you want to accomplish. And as you can see, we have the watch.log entry there and all the columns that we have just loaded from the database in the example before are now printed here as properties in this JSON array. Same example in JSON, doesn't look really different. Same example in XML, doesn't look really different. We are sending a different accept header if we have the XML format enabled that it respond with 200 return code and return that XML representation. I think that the XML support is not the best in Drupal 8, at least that is what Lin is saying. I'll get into that shortly. We are running a little low on time. And just to show you my last slide, that's the basic request pipeline that we are running in the AIDSRest module. The request is routed with a routing system to a generic request handler that pipes it into the serializer, which is an important component here, and hence the deserialized stuff to the resource plugin itself can manipulate and return data, turning it back through the serialization pipeline and then you have your response back. And that's it for me. Okay, we are running a little low on time, so I'm gonna speed through this and then we're gonna get to some of the questions. So, Klaus just showed you the pipeline that we go from REST module to serialization module. And that's one of the great things in Drupal 8 is that we actually have this separation between the logic of the REST module, so the logic of how you put things into the database and get things out, how you respond to posts and get requests, from the actual how you get a node into JSON and out of JSON. So, because these are separate parts, you don't need to write a specific, set of a specific resource every time you want to support a different format. So, the media types, we have in core, we have JSON, we have XML, kind of sort of. We don't actually have support for attributes or namespaces, it's basically just JSON with angle brackets, but that's good for some people. And we have HAL, which is, as I talked about before, a variant of JSON, or a different media type, a more specific media type, and you can use JSON as the base format for that. And so, the way that we actually are supporting it is we depend on symphonies serializer component for our support. And in order to interact with that, you get the serializer from the container and call serialize on it, it's a really simple API. So, you pass in the object, the format, and the context. So, that's the entity API object if you're using the entity resource that we have in core. And the context, you might pass in some variables that that specific serializer knows about. And so, the way that the serializer component breaks this down is into two steps. You go from your object, your kind of abstract thing, into a PHP array, it's called a normalized PHP array, and so that's the normalized step. And then you go from your normalized array and you encode it. So, you might be encoding that one array into JSON, you might be encoding it into XML. You can have different normalized arrays for your different formats, or you could just have one normalized array, and the difference between these different formats could just happen in the encodes depth. That's up to you. And what this does is it gives you fine-grained control over the markup, and it makes it really, not over the markup, over the serialization, and it makes it really easy to override it in very specific ways. So, let's say that you have a node, a node type, and that has a text and a text long field, an image field, and a taxonomy term reference. And let's say that the image field is not being serialized as you want it to, it just uses the file ID, because it's an entity reference. And you want it to actually give you the URL of the image itself. What you can do is you can actually change just the output for that specific field type, and the way you do this is by using a normalizer. Symphonies normalizers, the normalizer that they have uses a chain of responsibility. So, you have this list of normalizers. The entity reference item normalizer, the field item normalizer, the field normalizer, and the entity normalizer. These just happen to be HALs normalizers, the normalizers that the HAL format and core uses. And let's say we're normalizing the image item. So that's the object that's passed in is the image item field, it's a field item. And the format is JSON. And so the serializer will go through and ask the entity reference item normalizer, do you support image items being normalized to JSON? And it will say no. And then it will ask the field item normalizer, do you support normalization for image items? And the field normalizer has some logic that says it will support any field item or child classes of field items, so it will return true. So if you just wanna override the image item, the way that that is output, you just put a new normalizer at the very top of that chain and it will return true, none of the others will be checked. So that's how you get this fine grained control over the output in different formats. So if you want to hear more about serialization, I'm happy to answer questions, but I just want to go over real quickly what hypermedia controls are, and then we can get to the questions we have on Twitter. So I talked about level three earlier in the talk, the hypermedia controls, and they were a little bit complicated to understand. So I'm going to use an example that Martin Fowler, this really great thinker on software, worked up for describing hypermedia controls. So let's say that you run a hospital or you run like the National Health Service and you wanna make it possible for iPhone developers to create apps that people can use to book appointments or get their medical info. So you could develop an API for this and the way that this API interaction would go is the client, the phone, would get a list of open slots in the schedule by sending a get request. Then the server would return a list of open appointments. And in this list of open appointments, we're using HAL here so we have a little bit of understanding of the structure of the data that's coming back. You would find this list of objects and they might have a link here that's med.org slash rel slash book. So that is the link relation. That is the link relation for booking an appointment. And so if you saw that in one of these open slots, if you saw that link, you would know that you could use the resource that is indicated here to book that appointment. And so then the client would choose the appointment that they want from the list and would post to that booking URI. And they would get back, they would post it with the link relation, specifying a link to their patient identifier, to their patient resource, the thing that represents them. And then the server would return confirmation with a 201 created and the location of the thing that it had created. And then it would also return potentially links to tell the client what it could do next. For example, you might be able to use that same link relation to say that that's how the patient can look at their info, their patient info. Or there might be a link relation that allows you to cancel that appointment. So Martin Fowler identifies two benefits of this hypermedia. The first is it allows the server to change its URI scheme without breaking clients, aka decoupling. And the second is it helps client developers explore the protocol, aka discoverability. So decoupling, basically, an example of being coupled would be if you had a hard-coded URI, so like the appointment URI or the cancel URI. If you looked at the URL that you've been interacting with and said, okay, I know that that first part is just the base path and that second part is slots. That third part is the appointment ID, which I can get from somewhere in this message body. Because if they then go and change the structure of this URI, your application breaks. So if you use link relations, then you can just use the link relation as the key to access the resource URI for the resource that you want to interact with. So that's decoupling and discoverability. Basically, we already know about the patient link relation, and we know about the cancel link relation. Because we know about these, we can put these buttons in the iPhone app that correspond to these link relations. But say six months down the line, we see that there's a new link relation in the data that we're getting back called Ad Symptom. In an ideal world, because we're using URIs here, link relations should either be standardized in a short list of standardized link relations or they should be full URIs. So because we have this URI, we can look up what the API says this link relation means in an ideal world where it's a properly documented hypermedia API. So hypermedia in Drupal is still pretty open. We are using creating our own link relations for entity reference fields and the like, but we don't actually have documentation when you go to that HTTP URI to tell you what that link relation means. And it's still, there's still a lot of things we could do, like pagination and views. There are standardized link relations for pagination, so we could add that kind of stuff. So that's pretty open. We're still working on an encore and happy to have suggestions and requests. But I think a lot of this is also gonna happen in Contrib, so we wanna make sure that we're making it an architecture that makes it possible from Contrib. So that wraps up our session. If you have any questions, please feel free to tweet them. Again, that's hash rest, hash Drupal. You can also go to the schedule page and rate this session. And there's a sprint on Friday. There's a core mentoring sprint, so if you want to get involved in core, if you want to help figure out some of these hypermedia problems or other rest issues, you can figure out how to start working on core at this sprint, and that will, you'll learn how to do patching and all that kind of stuff, so please join that if you have any interest. So we had a couple of questions on Twitter. The first was, is the rest interface enabled by default? And the answer is no, it's a separate module which is not enabled in the standard installation profile. So you're not cutting that out of the box, you just have to enable it and configure it. Can I give some input about the WSTL? I think WSTL is related to SOAP services, so we are not doing anything of that in Drupal 8. How is performance, was one question, do we still need a full bootstrap? So the basic answer is yes, considering what a full bootstrap is in Drupal 8, it's a bit different, but of course for authentication we need the user system, we need the bootstrap, the serialization system, so we need to bootstrap quite some stuff and I think that qualifies as full bootstrap because we have to run through the entity API in order to validate it and in order to save it, so the answer is basically yes. Performance, it won't be hyper-fast because it's PHP and we are invoking a lot of hooks, it's the usual Drupal performance, but yeah, I wouldn't expect it to be really bad because it just executes a couple of basic things invoking methods in some APIs. Then we have, can you enable resources through the UI? The answer is not in Drupal Core but there is a contributed module that tries to accomplish that for Drupal H, it's called REST UI. So if you Google for REST UI in Drupal, you should find that contributed module. Is this CSRF token 100% compatible with iOS? I don't know. Yeah, I'm not sure about that, so if the person who asked this question wants to clarify what the concern is with CSRF token and iOS, then we can take a look at that. So how do you request a collection or list, like the views? What is the URI for that? Oh, that was the question, yeah. So if you, you can configure the path in the views administration, in the configuration interface. So with views, you create a new display and you also have to provide a path you can use, for example, slash node slash list for that path. And if you send an accept header with JSON there, you get a JSON response back. So that is up to you to configure wherever you want that to be. So the next question, is XML supported in views? If yes, can you do advanced nested structures? XML is supported in views. As I said, we don't have great XML support. The focus has been more on JSON, but that said, it's really easy to swap out your own normalizers, your own encoder if you need to. And if anybody's interested in that, I can talk a little bit with you outside of the session. So what other than standard auth, what are the other kinds of auth that you can possibly have? Yeah, currently we are thinking about three providers. First is the usual session cookie authentication, which you normally is used by humans, so it's not a good idea for web services, but it's possible. Then you need the CSRF token in order to protect yourself against malicious sites that do post requests on your behalf. The second one is basic authentication, which is included in Drupal Core. And the third one is OAuth, which is currently developed in Drupal 8 Contrib. So that won't be a feature of Core, but will be developed in Contrib. So it is two o'clock right now. Is the next speaker in the room? Hi, Larry. Okay, well, if you wanna come up here and set up, then we can just keep talking until Larry set up. Feel free to walk off and wander off to your next session if you want to. Thank you. So what about data validation, Klausi? So we are using the Symphony Validation API in Drupal 8, which means that when a post request comes in with an entity represented as JSON, we deserialize it. And before we actually save it, we make sure that the posted data makes sense. And with that validation API, you can, for example, check that some field is not longer than 255 characters. So that is covered by the validation API and is already implemented in Drupal 8 Core. One question was, does JSON work as well? Yes, we use HAL plus JSON for post requests, but you can also get nodes in a very primitive JSON format. So that should work. Can you deploy configs such as views to production from a staging site? So currently, in the REST module for Drupal 8, we are only implementing that for content entities. So we are not providing any support for configuration entities and how they could be deployed over a RESTful interface. But it really depends. Do you really want that? Because in Drupal 8, you can version your configuration files and deploy them with Git, for example, so you wouldn't necessarily need a RESTful interface for that anyway. What else do we have? If you're putting something, you actually want to replace it as is. And for entities, that doesn't necessarily make sense in Drupal 8 because there are a lot of post-processing and hooks are invoked on saving. So what you're sending there, what you're putting there might change. So it might not be the original thing that you put there. So put doesn't make sense. And we decided to go with patch instead, which clearly defines that you are updating parts of a resource. Have you thought about versioning of REST APIs? That is currently a big open question in Drupal 8. So I think we are just in the beginning of exploring how a RESTful web API can work for Drupal 8 and work for core. And versioning is, we didn't get that into our agenda for Drupal 8. So that is still an open question, how we can provide different versions of one API on one Drupal site? Sorry, I can't give you a more concrete answer about that. Is there view mode support for get request? That's a very good question, but currently no, it's all driven by the serialization system. So you cannot specify any specific view mode that should be used on a get request. It would be possible. Add that support from Contrib. Thank you, Larry. So Lin is saying we could add that support from Contrib because we can easily override the serialization components that are invoked. And the context could be used for that to find out which view mode should be printed. So I think I'm leaving. I will be out there in the hallway for another 10 minutes. So if you have any remaining questions, just get out there.