 So let's get started. Welcome everybody. Glad you've been here. Hoping you have a great Drupal com. So yeah, a few hours left. It's all done, except for Contribution Day tomorrow. Be there. Today we're going to talk about how JSON API 1.1 will make Drupal better. My name is Bjorn Brala. I've been the babysitter of Little Rooster for a while. He's a good friend of mine. He's being sold right now. I'm not very happy about that, but it's OK. I'm a CTO at Swiss, a Dutch Digital Agency. I'm a core maintainer for JSON API. And I'm a member of the Board of Dutch Drupal Association. And I do way too many other things also at the moment. Yeah, no worries. So Swiss is a Dutch Digital Agency from Leiden, the Netherlands. And we do sustainable digital transformations, mostly for non-profit and government and health care. And we are big fans of JSON API. So that's why we sponsor my time on JSON API in core. But we also have quality PHP clients for JSON API, which we also have outsourced and used quite a lot. Our default is JSON API. If we need to communicate between systems, first try JSON API. If that's impossible, then we might try something else. So JSON API 1.1 is the minor upgrade, or are we looking at really a major improvement? One of the good things that JSON API promises is the fact that new versions will always be backwards compatible. So we never remove. We only add new parts to the specifications. And that's great, because that makes my life a lot easier, and perhaps your life a lot easier also. Because if it works, it works, and it won't suddenly break. Because a new revision comes out, and you need to fix your stuff. There's only new goodies to use. So that's good and fun. So it makes a really good fit also for Drupal, because we have a very, very strict backwards compatibility promise, and that JSON API helps us keep that promise. If we, JSON API has had a few changes in regards to 1.0. In an overview, there's a few things that have been added. We've got profiles and extensions, so we can start extending this back or describing this back better. There is a new feature called add members, which I also want to call cheaters. But we'll get back to that later. There's some improvements in how errors are handled and how you as a developer can see what is wrong. There's updates to link objects, adding support for the thing everyone uses. There's a new describe by member, which we will talk about later, because that's one of the awesome things that's really gonna be valuable for us. They added local IDs, which I'm tempted to just ignore, because it's complicated and not extremely useful. And there's a ton of little editorial improvements where writing this back is pretty hard, so small words matter sometimes. So it's mostly editorial. If we first have a look at profiles and extensions, which I think is the meat of the new JSON API span, profiles and extensions are two ways to define or extend the specification. So on the one hand, you have extensions, which mean you create new things in the API. They code all those, defining additional specifications, semantics. We'll get back to that later. And you'll have profiles, because JSON API has quite a few parts of it where it's like, well, the implementer can choose how they do this, for example, filtering or pagination or stuff like that. But something that's quite important is the semantics. So on the one hand, you have the specification semantics which is just everything described in the specification. And they collectively call those specification semantics. So you cannot touch those, but there are certain exceptions to that rule. There was our explicitly mentioned in the specification. So that certain document members or query parameters or perhaps even processing rules can be defined by the server, let's say, the JSON API server. And those are called implementation semantics. You have to communicate though, what your profiles are and extensions are. They choose to do that through the content type and add in the profile URL in the response. That's pretty handy because if you're talking to an JSON API server, you as a developer can see what kind of profiles are supported by the server and directly go to the documentation or definition of what that profile means. So discoverability gets quite the upgrade. For extensions, it's pretty much the same. Just a C, it's a profile in the header. And that way you can tell, yeah, I'm gonna use this. There's also a human readable version, yeah, because headers are annoying. At least I find headers annoying to find. But in your response, you can have just, there's a list also from, yeah, these extensions are supported or used by this server and these profiles are used by this server. That way you don't even need to look at the headers or whatever and you can just have a look at your response. They do say, do not use this to know as a client what extensions are supported, use the headers. So this is just quality little fly field. Let's have a look at the extension that actually does extend the specification. So adding one of the things you could do is, for example, the JSON API does not have the put verb, for example, that's not part of the specification. You could have, could describe that and put your own logic behind that if you like. Not sure why you would do that, but you could. One of the examples that is used by JSON API itself is using adding versioning to request and responses. So here you have a response as you would get, yeah. So we have the extension communicated that uses the extension version and there's a new weird one in the middle of the response. We have a version, colon, ID and a version. What you might notice is the prefix, yeah. So there's extensions have to define a namespace, let's say, in which they communicate. So if they add something to the specification, it always needs to be prefixed with a namespace. This is mostly for lessening the chance, let's say, for different extensions to conflict because you're always namespaced. And also this means that it automatically will never conflict with the JSON API spec itself because they will only define attributes that are letters A to Z. So if you're not using those, it will never break. At least that's what they promise and let me leave that. So the prefix might be a little bit cumbersome in ways but it does allow for cool stuff in combining extension and making sure that that's stable with something you can count. An actual published extension is atomic operations. I'm not sure how many of you have actually run into the problem that, okay, I need to create a new resource but before that I need the address and I need an X and a Y and a Z and I'm doing 57 requests before I can finally create my main resource. That's something that's at least annoyed me quite a bit in how you need to handle JSON API. So this extension tries to solve that by adding atomic operations. An atomic operation is a set of operations that either succeed or fail altogether. So let's see it as if you start a transaction, you are doing quite a lot of different operations and that ends the end. If one of those has failed, you just roll back to before you where you are. So you always know that it is. So it adds a new endpoint where you can define operations. You can say where does this operation need to go? So here it's in the example, it's on the articles and relationship comments and it adds a reference to some comments. Yeah, but that's only one thing that this could be a normal JSON API request but it gets interesting when you start doing multiple things. So what if I first add the author in my atomic operation and after that, add that author to my article. So you have a single request to do your whole operation and that simplifies parts of the logic at least from your front end. It's quite a lot for your consumer. So this could be pretty useful for Drupal, yeah? I mean, at least pretty useful for JSON API consumers but because yeah, creating multiple resources is pretty much a pain. I've been thinking about implementation though. This might be a little bit harder than it looks at the service, yeah? Because I'm not sure we completely, yeah. That's gonna be a little bit hard so it's not gonna be something that's coming to JSON API in the next six months or so. But still, it's a great chance and I think that's something we should explore and would make the life of a lot of consumers a lot easier. So that's extensions, yeah? The second type we talked about is profiles. Profiles are about describing your specific implementation of JSON API so the easy one to look at is filtering because the filtering in JSON API for Drupal is really great and extensive and you can do really a lot in filtering your resources. If you compare this to, okay. I've not seen such an extensive filtering system in other JSON API server implementations. Not in the Laravel ones, not in some of the Rails ones I've looked at quite a few. This one is really great. So that's the prime candidate for a profile. Let's have a quick look back at how filtering works right now. So the easiest one is just filter on field name equals a value. So this field should be this value and you can filter on another one and then it's just filter on this field is that value and that field is another value. So this is a short syntax but there's also the long syntax which gives us the power to do a lot more. This is, here you see the short version for someone first name Janice and the long version where we specify three separate parts of the filter. So the path which could be a field or field enumeration, et cetera. Operator which is here in encoded equals sign and the value which is say, what a Janice. I don't know who Janice is though. And there's a lot of operators. Yeah, we've got, because we have, we use entity queries in the inside of JSON API. We can do a lot. We can do equals or not equals greater than is not in, et cetera, et cetera, et cetera. And that's great. But, so you could do the first name should be one of Janice, Joan and Jeff. No problem, we can do that. And it even supports more things, yeah? So show me the users with the job developer with the first or last name, Smith. And there you can do something that's called condition groups. So you can create a group, say if it's and or and then build your filters through that. So here you have a first filter which is meant in both or group where the first name is Smith or the last name is Smith and lastly and job is developer. This is something that is documented pretty great in the JSON API documentation, how to use this, how to do this. But perhaps for people who consume JSON API which not always will be group of developers it's easier to discover if we actually have a profile implemented. And therefore improve the developer experience immensely because the people consuming Drupal JSON API will start loving JSON API more because it's easy to discover how it works. And you can start describing the API inside API. I've talked to quite a few people about what this could mean and how we can do. And I don't know if many of you here have used OrbitJS. No, impressed. It's a great JS client for supporting also JSON API. It's built by the guys who are also built Ember, which EmberJS, which are the founding fathers, let's say, of JSON API. So it's really the people who bought up JSON API also made that client. And I talked to them and they will support our profile if we publish it. So then people using OrbitJS will have an easier time to, for example, use our free access. Therefore, of course, we have also our own JSON API client which we support and which we will add profiles, of course. Let's take a good example, yeah. Also good relations with the guys creating the Laravel JSON API server, create implementation, and because of Laravel's eloquent models, which is the database you're in, it's really easy to do the same field as there. So he would accept also the same profile in the Laravel JSON API server. So something like that could help Drupal immensely to one, strengthen the ecosystem around JSON API, but also get more of the word out about how good the JSON API of Drupal is, which would be great. You do free, of course, if you publish a profile, you do freeze in a way, and the way your filtering perhaps works. But I don't think that's really a problem because Drupal is also quite, won't change how things work normally. Yeah, we have the backwards compatibility problem, promise, so the fact that it's written down doesn't really matter that much. So I'd like to ask you if there's, if you look at profiles and extensions, what are the kind of things you might run into or you'd like to see as, yeah, that's an extension of profile. Someone I've done, yeah? There's a few things that we could do to better communicate our API. There's a few things we do a little bit weird. So we have a partial success. That's a bit of a weird one when you get a list of entities. It might not completely feel what kind of feel, but not feel. We'll talk about that more. For short, it is a little bit weird. And pagination is another one of those parameters that JSON API doesn't tell you how to do it if that's scourge-based or whatever. So partial success is something that Maciej and Ipso already wrote the specification for, which does need a good look and good review to see if that's complete. And it's mostly about the fact that resource lists could exclude entities in the list. So for example, if you have a list of articles and you don't have access to one of those articles, it will be removed from the list. It's a bit of a annoying feature, but a feature that will last. And there's quite a few people who are a bit confused about that and how to use that. Another one is sorting. We have the normal JSON API way of sorting using a single parameter and combo separated field list, either with a minus for dissembling or even sorting on relations. But there's also a long version, which is not part of the spec and could be something we describe, where we split up the different parts of the sort into array values, let's say. The last one is pagination. In Drupal, we chose to use offset and limit. There's a lot of different paging strategies available. So it would be good to at least tell the consumers how our pagination works so they can adjust to that. A lot of the times you don't really need to build your own pagination handler because there's always like next links and previous links and stuff like that. But it is still informative on how could you build the pagination list. There's a thing that's perhaps something we need to be wary of. And that's the fact that it's good that everything can be specified or written out or published as a part of the extension of the specification. But so we could say, yeah, this server for install has versioning enabled so you can expect versioning information in your request. Or it has the metadata can contain internal IDs or the taxonomy name is in the metadata of a taxonomy and stuff like that. We could specify all of that, but I'm a little bit wary if that's really worth it to go into the full, try to fully specify how our requests look. It's something of a risk, really. So next up are cheaters, which are ad members. The members in JSON APR are basically JSON attributes. But because there's an attribute in the JSON API request, that's a little bit confusing. So they called it members. Members is a little bit broader also because there would also be the name of a request parameter or get parameter or stuff like that. Ad members are something weird. So there are members started with ads, which is pretty obvious. And the state that they can appear anywhere in the document. So it doesn't matter where. Yeah, sure. You wanna add members? Yeah, sure. Pop one down, that's fine. No problem. And ad members should be ignored by clients in service as being real data. So if an ad member in an attribute is not an attribute of that resource but just some sort of metadata information. One of the things you might be able to use that for is JSON LD. So what if your JSON link data is in the JSON responses of your JSON API. Of your JSON API server. This is something that's now allowed and what you could do. I'm slightly wary about, I mean, it's interesting. Yeah, sure. I'm not sure if this is a way we want to go. This does allow for the JSON link data to communicate that in the single request. So you could have a frontend application that then also knows the whole LD. But it is really a little bit of cheating. I mean, you could have it anywhere in attribute or somewhere nested or even somewhere in the links section. And I'm not sure if we really, really want to do that. Unfortunately, we do need to at least acknowledge the fact that that's a thing. So we need to handle ad members or more precisely, we need to ignore ad members. But that's perhaps a few chances for my chime. I mean, what if one way attributes? So, I don't know, some computer property that is not really saved in the entity, could that be useful to communicate through an ad member or image derivatives? Yeah, you have an image field and one of the solutions the community came up with is communicating that in the metadata of the resource. Might be easier to read if you have an ad member near the image fields with the different image styles, it could be. And of course, the obvious one is JSON data and perhaps even metadata information where you can communicate some of the information you get there, move it up, but it's not information you want to send back or update or put or do something with. So, is it worth it? I'm kind of skeptical of using these kind of random members in documents, but I can imagine that if you are in control the server and the clients, that it might be an easy way to implement some extra communication to the front end. But a lot of time I feel that the existing metadata information facility should be enough because you have already improved from there. It's only a little bit far from the source of the data. Now the next one is the improved linked objects and RFC 8288 or is it 8228 links? So, basically web links, yeah? So, JSON API decided to at least join and specify that you can make links, web links, and this does open up a more standard way of representing links. The fact is that Drupal already uses those properties, it's all things like the rail tag or some other of the allowed web link tags in their links, but now it's official that you can do that. This does open up, it doesn't really open up new possibilities, but it is a trigger to perhaps think of what kind of links are relevant in the context of a resource in JSON API. So perhaps you always want the after link if applicable. Maybe you should want a link to the collection endpoint of a resource or at some point you might want another form and link that. It's all valid relation, rail tags for links, especially when if we get an endpoint for version history that would be really awesome if you could just link in the resource too, okay? Where can I find the list of versions for this resource? We cannot do that now. Same for working copies, yeah? Because if you have workflow or you have forward revisions knowing the fact there is perhaps a forward revision for you and previewing that, could make it a lot easier to get there. So that's fun, I think, and it could help discoverability quite a lot. Next up, the described by-member. And this one that I'm really excited about. The described by-member is a link to the description document of a resource. So this could be JSON schema for perhaps OpenAPI for the specific resource you're looking at. And that's just insanely useful. So this could be a link to, this is a comment and there's a related link to the comments overview. And there's a described by where you can actually show the schema of the comments. This could be extremely useful for Drupal, especially in the near future. I mean, having all resources described by schemas and enabling things like validating the data you are about to send to your endpoint. For example, there are great validation packages for just giving data, is this valid scheme. But also for the developers again, if you're consuming an API and you wanna know how the resource looks, here you go, this is how it looks and you just have it in your request. So you don't need to give me the endpoints, give me access and I know everything. That's insanely useful. This is closer by that you might think. In Pittsburgh, sorry, there was a, there was a Pittsburgh initiative, yeah. And one of the things that got funded was JSON field storage and schema support. So, okay, the JSON field support, that's very hard because we do a lot of things with different database backends. But one of the things that also added was added there was schema support. Brett Jones is actually working on that right now. And we at least have a way of doing it and a way of using tight data from Drupal and serialization of the normalization of resources, how we do it right now to generate actual schemas of the resources you ask for. So there's actually a pretty good chance that in the coming months we get support for schemas generated in Drupal itself. And that's gonna be really, really great. Especially if we start communicating that to the people who use our API. So summarizing, there's a few things that are happening that might be happening. One is we can finally share our awesome implementations with profiles, which means that we can get better clients, get better support outside Drupal for the API in Drupal, which is gonna help immensely. There's a few published extensions. We should actually evaluate it and see if it's realistic to either implement those or use those as inspiration to make our API better. The whole using of schemas to communicate resource structure is gonna be a game changer. I really feel that it's gonna be a game changer. And yeah, that member really is cheating. I don't know if it convinced me otherwise, but I'm not gonna do it. And we should explore some new more link options in the future to see what's useful for us and for the people who consume our API. There's a few other exciting things I want to mention just in regards to JSON API, because there's people here who like JSON API, I hope. So, there's one extra. So the publishing of the profiles, yeah. The schema support that actually is coming. Vim Lears is working on a conflict validation which will end up enabling us to expose conflict through JSON API. And then perhaps in the future, we can actually do what we are dreaming of for like, I don't know, seven years. And that's, what if there's a decoupled back-end interface? God knows. And lastly is Brian Perry, who did the decoupled menus initiative earlier, is now working on a Drupal API client, which is mostly install and go way to communicate with JSON API in the actual node, yeah. So that's also a great initiative to at least make it easy to get started. So there's really a lot of things to get excited about. And I think that if you look at what's happening right now, that we have a pretty good year in front of us with a lot of innovation and a lot of new features and a lot of ease of use for JSON API. Thank you for your time.