APIs, with Jess Archer
Matt Stauffer:
Hey, welcome back to Laravel podcast season four. Today we're talking to Jess Archer, Archer, something like that in Australiensis. She's going to talk to us about APIs, and all sorts of other stuff about building them. Stay tuned.
Matt Stauffer:
All right. Welcome back to Laravel podcast, season four, where every single episode is about a specific topic. And today, then remember when I try to pronounce people's names, I try to pronounce it in their native language. Today I'm talking to Australians, an Australian, and every single time I hear her name, Jess Archer, Archer. I hear either her or Michael saying Jess Archer, I think Archer or something like that. So just like everybody else, that's going to be my attempt at Australianalyzing it.
Matt Stauffer:
Jess is going to be talking to us today. Once again, just like we did with Samantha, where I told her here's 10,000 different topics, with Jess, I'm going to give her one topic, which is so massive that there's no way you could possibly cover it in a single episode, and we're going to just try and do it anyway. As we do at the beginning of every single episode, Jess, can you just tell us if you were to meet someone in the grocery store in the days of your... when we went to grocery stores, or however else you would meet someone. How do you tell somebody about what you actually do?
Jess Archer:
I tend to say I am a web application developer. I differentiate that a bit from a web developer, that might make a website. I tend to make more interactive websites. Things like, for example, Facebook, or internet banking, things that tend to have more buttons, forms where you type things into, that are more interactive, that'll store information. That's how I describe what I do.
Matt Stauffer:
I like that. I'll often say, if you have to log into something, or if you change something and it changes, that's more like a web app. Whereas, a website is you go and it's just always the same thing, and get information off of it. But, I like the way you said that. If you met someone who actually understands programming, what's your actual day job and what do you... what are your projects, and what kind of tech do you work in and everything?
Jess Archer:
I probably would say full stack, full stack Web Dev, with a passion for Laravel view and tailwind. That's my stack of choice these days. I fled around a little bit. I do three days a week for a medical technology company, and I work with Jay Mark of Laravel shift, a little bit help him out with stuff, and then I just try and work on my own side projects as well.
Matt Stauffer:
Very cool.
Jess Archer:
I like the variety, and I like doing the full stack from ... sometimes even designing them UIs, all the way down to ... I've got a server in my office here that's running tons of docker containers and -
Matt Stauffer:
Yeah, I was about to say. You're a VIM wrangling Linux user, So you're definitely following geek. I didn't know you could do design too. What's the name of your SAS? Is it GiftyDuck? Is that right?
Jess Archer:
Yeah. GiftyDuck is a little SAS I started with a friend, just designers. It's like an online wishlist, almost like a social network wishlist type.
Matt Stauffer:
Is it similar to... my family uses Amazon wishlist to share. Is it like new Amazon version of that? Or is there more to it?
Jess Archer:
Yeah. You can put any URL you want, and it uses web standards to try and scrape information about the products, depending on which format they're using. Basically, like when you go to Google, you type in a search result, and it knows the price, and all that in like the mint. So using the same metadata to try and scrape as much as I can about the product so that you can add it to your wishlist and-
Matt Stauffer:
Was it called JSON, something LD or JSON something D?
Jess Archer:
... JSON LD's one of them-
Matt Stauffer:
Others more than one.
Jess Archer:
... There's so many now I can't even think of them off the top of my head, but some of them are separate sort of files, some of them are headers, some of them are just metadata like you put on the HTML elements on the page elements.
Matt Stauffer:
Mm-hmm (affirmative) Meta elements, yeah.
Jess Archer:
There's a few of those, but it's completely free and we make our money by, if you put an Amazon link, or any link with any of our affiliates, we'll put our affiliate code on the end of it-
Matt Stauffer:
It's brilliant.
Jess Archer:
... But it doesn't cost anyone else anything. If you put a link for a place we don't have an affiliate link with, it's fine. We dodn't get anything from it, but that's fine.
Matt Stauffer:
Very cool. You got a lot of things ... Wait, what's what is something in the fires? Lots of things going on, I can't remember the analogy-
Jess Archer:
Irons in the fire, I think.
Matt Stauffer:
... Lots of irons and lots of... but other folks may know you from doing the podcast with, the base code podcast, and also for being a speaker at LaraCon. So I just want to get context from everybody. How did I do on the Australian version of your name by the way? Did I get it? Did I do okay?
Jess Archer:
It sounded to me a bit more British. I would say just Archer, but I don't know whether... just Archer.
Matt Stauffer:
Just Archer, Archer. Australian, South African and British are... Australian and South African are almost the same to my ears and-
Jess Archer:
A lot of people say Newzealand is the same as Australian.
Matt Stauffer:
... British is not at all. Maybe, Well, I definitely can't tell the difference between those two. I didn't even know that you would have told me that there were different. I don't know why South African is so similar, but I often meet someone from South Africa and assume at the beginning that they're from Australia, I don't know why. British, I can hear the difference, but I can't do accents so...
Matt Stauffer:
Anyway, sorry. All of this... we're... I don't know how many minutes in, I think we're five minutes in, we haven't got to it. The topic today is APIs. We are eventually going to get to APIs and Laravel, but we're just going to start with APIs in general. If you had to describe the topic APIs to a five-year-old, how would you describe?
Jess Archer:
I think it's important to know what it stands for. It's an Application Programming Interface.
Matt Stauffer:
All right.
Jess Archer:
Then interface, is basically when two things communicate with each other. The most familiar interface you might be familiar with is a user interface. Which is a thing that lets a person tell a computer what to do, and to get information from a computer. Everything you see on a screen is part of a user interface, and it might be text, buttons, text inputs. When you think of something like YouTube, you're probably thinking of its user interface, and not all of the other stuff that's behind it.
Jess Archer:
An Application Programming Interface, or API is another type of interface. But this is an interface that allows computer programs to talk to other computer programs, to send and receive information and to give instructions. How's that?
Matt Stauffer:
That was freaking fantastic. You sound... in only the best ways, you sound like a college professor. That was a hundred percent. For a second there, I was like, this is so accurate. It probably is not kid appropriate, and I thought it was like, no, it's completely kid appropriate. My kid ... my eight year old could totally could have handled that, I don't know if my four year old could have, but she's not five yet.
Jess Archer:
It lets computers talk to other computers, or even just computer programs talking to other computer programs, even within the same big computer program.
Matt Stauffer:
Also, just the idea that, what is an interface, is really helpful. Because the interface, like we often talk about the technical definition of interfaces, like what is an interface, and PHP, or whatever.
Jess Archer:
Like a PHP interface.
Matt Stauffer:
Yeah. But an interface, is a thing outside of the programming world and it should give us some context of describing. It's the interface between A, and B, it's the interface between a person and a computer-
Jess Archer:
Between two different things. If two people are talking and having a conversation, they're interfacing.
Matt Stauffer:
... Yes. That's awesome. We definitely, are at the point where an API is a lot broader here, than what we often talk about. Now take me up to programmer level and talk to me about either a programmer who has never thought about APIs, or maybe has a really narrow understanding of what an API. Could you describe what an API is to a programmer?
Jess Archer:
Well, most people might be familiar with a typical REST ,or HTTP, or web API, where you're sending and receiving JSON or XML payloads. That's what a lot of people think of when they think of an API, but an API is effectively any entry point that allows access to another piece of code. You can think of things like the public methods and properties on the class, as the API of that class, the props on a component, like a view component or a blade component, the props or the API of that component.
Jess Archer:
Even the program programming languages you're using such as PHP, is effectively an API, or an obstruction to a lower level of code in the computer. So PHPs, like every method you look at, has an API and use an API to do things on the lower level. Then that... the languages underneath that, again, are going ... using APIs in the language below them. So it's APIs all the way down.
Matt Stauffer:
I love that. I love that because it's ... once you say that, you imagine looking at API documentation that says, here's the end point, here's the things you're allowed to do with it, here's the parameter it takes. And you think about the PHP documentation, it's the same thing. Here's the method, here's the things that it takes, here's what returns. That's really cool.
Jess Archer:
It describes like... the documentation for an APIs is generally describing the input and the output. What you can send to it, and what you can expect to get back from it. It's the same for a web API, or a method in PHP. It's all just describing what the interface is going to be.
Matt Stauffer:
Or even in some ways, interaction between two people. You send this to that person, you can have a little bit of an expectation of what you're going to get back from them.
Jess Archer:
This is true. There's social protocols, and all this sort of stuff.
Matt Stauffer:
This is deeper than I expected. Cool. Those are APIs, so one of the things that you said before we were talking, I don't know if you said it right now, but I love was, the idea that people can often talk about... that the API of a package, or a piece of code, or something like that also. And that's something I heard a lot in the Laravel world where, for example, Taylor will talk about often, you... he'll use the word API to describe, I wanted to give it the simplest API possible, or I wanted to, whatever.
Matt Stauffer:
I feel like that's the most common usage I've heard of somebody saying API outside of the context of a REST API. You have now given us all context to understand why that is that phrasing that he and other folks are using. And I'd really appreciate that.
Jess Archer:
With a package, for example, the API might not be specifically the API of one class, but it's the API of the... what the entire packages is affording you. There might be multiple classes you can interact with, and it's... the API is the overall interface with that. So it can be a little bit abstract, but then as you dig deeper, it's, what's the API of this class, what's the API of this method.
Matt Stauffer:
Mm-hmm (affirmative) And you also just used another word that I hear people say often, and I it's new to my vocabulary in the last four or five years, is affording and affordance.
Jess Archer:
Adam Latham really got down to my vocabulary.
Matt Stauffer:
I was just going to say, that's very much an Adam thing talking about affordances. It's interesting because, when I heard him talking about it, I realized that the main time I'd heard it prior to that is in user experience design, and they talk about afforded. It's like not even just user experience design and the web, but also in building refrigerators, and stuff like that. They talk about affordances. It's really cool to think about the fact that, like a refrigerator, there's some classic example, can make it possible for people whose hands don't grip as well to open the refrigerator in a way that they couldn't. It was something in the kitchen. I can't remember what.
Matt Stauffer:
And similarly, we're building interfaces, not between a person and a refrigerator, but between a person and a computer, or a programmer in a piece of code, or whatever. And so it actually has a lot of overlap, even in just the way we can think about like, how do you build refrigerators, such that everybody can use them not fully physically abled in their hands people, right? Like how do you help a grandma who doesn't have full whatever. Similarly, how do we build these packages with APIs that make sense for more people, or working more context, and so there's a lot of overlap there. I really appreciate you introducing that Concept.
Jess Archer:
The idea of an affordance is, it's like telling you what it can do as well, so Adam's example was, I think a chest of drawers. And the handle is the affordance, It communicates with you. You can see what you can do with it because the handle is right there. Whereas, you'll get some sort of fancy cabinetry that doesn't have handles, and it doesn't communicate what you can do with it. It's almost like an API with that documentation.
Matt Stauffer:
Yes.The first thing you do is walk up to it and just rub your hands all over it hoping you can figure out what
Jess Archer:
It's like you push it, see if it's one of those ones or is it a pull one.
Matt Stauffer:
Yes. Push, pull.
Matt Stauffer:
I love that. We're talking about APIs a little bit, but let's dive a little bit further and now... unless there's more than you wanted to go there, then let's talk a little bit about what people assume. You got something else?
Jess Archer:
I do. One thing I think is really, really important to remember that, although APIs are for computer programs to talk with each other, the main consumer of the API, it's actually the developer that's writing the program. When you are building your APIs, and writing an APIs, whether it's in a class, whether it's a web API, try to be always thinking of the human that's going to be writing the code that's interacting it, not just the computer on the other end, but the human as well.
Matt Stauffer:
I love that.
Jess Archer:
The best APIs I've ever worked with, clearly were written with the humans in mind, not just the computers, in terms of the documentation, but also just the naming of things, the conventions, all the things that make sense that computers don't care about. Like compilers don't care about what's going on with naming of things and consistency, but humans do.
Jess Archer:
It's important to us, to make things a pleasure to work with them, and that's what comes down to developer experience, which is something that I'm really passionate about.
Matt Stauffer:
I can tell.
Jess Archer:
Even the internal code that we're writing. I think about my own developer experience in three months time when I come back to look at it-
Matt Stauffer:
Don't remember what you were doing or why you were thinking about it.
Jess Archer:
... Is this going to be clear what's this is doing, what... is the intent clear of the affordances? All obvious.
Matt Stauffer:
I love that. I love the idea of making it obvious because, it's like, not just does it work? Not just, I mean, I don't know. I think that making it obvious is one step further in the direction of trying to make the X really good, the developer experience really good, beyond what I think we tend to think about. Because we tend to think about like, well, I put it all there, it's all there. But just because it's there doesn't mean that it's discoverable or it's intuitive.
Matt Stauffer:
I love that idea that you're talking about, and this is true in APIs or packages, but also could end up being true in REST APIs, what does it look like for things to be discoverable? Which is a big term that they use in the official REST APIs, but intuitive. Well, how do we make it make sense? Did you, were ... so what's your coding background? Do you do like CodeIgniter and all that old crappy PHP stuff back in the day or?
Jess Archer:
I started with just PHP on its own. I wrote my own CMS at some point, because at the time I think WordPress had never been used on anything, and I was like, I need to make my own. Then at some point, WordPress far exceeded what I had built, so I'm like, now I'm going to go with WordPress-
Matt Stauffer:
I did the same by the way. So...
Jess Archer:
... And then I had a similar thing with frameworks. I'm like, these are just so heavy, I don't like them. I would build my own frameworks, but then one day I discovered Laravel I think through Jeffery way, and I was doing a VIM course, or a redneck course, or something called net tuts, and he was using a blade file as an example, and I'm like, what's this Laravel thing you're talking about? And so I think, I discovered Laravel and all of a sudden I'm like, I'm never writing my own frame ever again. I'm like this ... Laravel is very opinionated, and I agree with all of its opinions, and it has taught me things that I would never even have thought of. It's just ... it's such pleasure to use.
Matt Stauffer:
Well, I asked that because, that's a perfect segue, I asked that because, back in the Code Igniter days, when we would write internal APIs, and stuff like that, there was no convention around using, plural of the Singh thing slash one. There wasn't any conventions around posting to the end point to the plural of it to create something or anything like that. And so I look at APIs I wrote back in those days, and I just made it up, and some of the conventions worked, and some of them were terrible, but we just had no idea, and so they weren't discoverable, right? Because we... there's no way to know because there's no standards, there's no reasonable expectation of what an API is going to shape.
Matt Stauffer:
I learned, like you said, I learned through Laravel, what a healthy API shape would look like, and then now that's what I do on my APIs, so I totally feel you. There's only one thing I didn't agree with in Laravel in the beginning, which was the fact that it's sorted the imports by length instead of alphabetically, it drove me nuts. It's the first thing I changed a lot of time, but they don't do that anymore, so it's good. We're good. Everything's good. Now, I agree with that.
Jess Archer:
I'm always a fan of conventions over preference. I think back in the day, I always preferred tabs over spaces-
Matt Stauffer:
Me too.
Jess Archer:
... But I would prefer though to use the common convention. I don't want my cards to be unique or to have my personal flavor on it.
Matt Stauffer:
Like I love that. I love it. Anything else you want to share about them before we start diving into REST and JSON APIs?
Jess Archer:
No, I think we can... let's dig down into a specific type of API.
Matt Stauffer:
One particular type of API, which is the most commonly discussed when somebody uses the term API, that's most likely to be talking about a web based API. Probably, going to be consumed by either JavaScript, or a mobile app, and it's going to be probably REST-ish, probably JSON, right? Can you talk... what's that?
Jess Archer:
These days it will be, yes.
Matt Stauffer:
These days, yeah. It wouldn't be XML sometimes still and would have been SOAP in the past. But I think in the Laravel world, that's the safe assumption, right? That's that where you're going. And we're certainly narrowing this down, like we're not even just taking it from APIs to HGB APIs, we're not taking it also the whole way down.
Matt Stauffer:
Actually, let's step back a little bit. Could you just give a really quick high-level of HTTP APIs in your knowledge? I mean, I'm not asking you to give us a full history lesson, but how much... could you share a little bit about the history that you know of APIs, and SOAP, and XML JSON's, stuff like that. Have you done much experience ... have you had much experience with them?
Jess Archer:
Whenever I think of the word SOAP, I get traumatic flashbacks.
Matt Stauffer:
Got it.
Jess Archer:
They were not, in my opinion, didn't have good developer experience at all. They would just hard, the... even when you had documentation, it was just so verbose and it was so hard to figure out what was going on. I don't know whether it was because I was less experienced at the time, but, SOAP is not, my friend. I think API has really started to make sense for me when I learnt about REST, which is, sorry, Representational State Transfer, I think is the... is what it stands for. It is quite sad to say representational.
Jess Archer:
I think that was when I started to realize that APIs could actually be something I would enjoy working with, and even creating, because I think prior to that, I'd only ever worked with other APIs and they weren't REST, and in my head API was a dirty word almost.
Jess Archer:
At that time, all I thought of with API was web APIs as well. I think the idea with REST was really good. It really leveraged what the HTTP standard had been set out to do, and using a lot of the things that had already been built into it. A lot of the different HTTP verbs you might typically think of, like get and post as being the most common ones on a website, but there were a lot more other ones that weren't really being used that often. Things like put, patch, delete being the extra ones that filled in a lot of the gaps, and then even status codes.
Jess Archer:
I mean, I remember when I started building a website, I didn't really know what a status code was, other than like a 404, I didn't even really trigger that when there wasn't 404, there was still maybe another status code, sorry. As I started to learn this whole other language for describing what the API was doing, and it was based on things that had been around for quite a long time. I mean, I think REST in itself has probably been around for longer than I appreciate, but...
Matt Stauffer:
I should know this because I gave a talk about its history, but I can't remember actually when it came about. But you're absolutely right, that REST itself was designed to reflect an understanding of the best parts of the HTTP spec. Like they ... and I feel like... I remember there was some aspect where he actually like did...they asked a whole bunch of people questions about, what's good about it, what's bad about it, what's used, and what's not used. And it was all around, like how do we implement these things? I'd love you introducing that concept. If you had to give the simplest description to a program, we're not doing a five-year-old, of what REST is, what's a REST API?
Jess Archer:
I tend to think of it as resources and collections. The collection just being a collection of resources, and a resource being an individual object in your business domain. If you're doing an invoicing app, an invoice might be a resource. So REST basically, allows you to transfer... like this what the... where the state transfer part comes from REST.
Jess Archer:
Prior to REST, I think a lot of people were using RPC, or Remote Procedural Call, with the API, you would send an action, and just say, do this thing and you'd make up some sort of payload. Whereas, REST defined a way of saying, this is the representation of this invoice, in whatever format, commonly JSON, so this is the representation of that. As an object with properties, it might have the price, whether it's paid.
Jess Archer:
To me, REST was always about transferring that object from... If you're creating it, for example, transferring it from your browser, to the API server, and you're saying, this is the state of this, this is what it is. That's when you're creating one. When you're retrieving one, you're again, you're requesting that object out. And when you're updating it, you're potentially replacing it with a whole new one, but it's got the same ID, or you are maybe just tweaking one or two properties on there.
Jess Archer:
Then when you've got collections, that's when you're dealing with the resources as a collection of objects. You might be dealing with invoices as a whole, so you collect ... you're requesting a listing of all of the invoices, or maybe just all of the invoices matching a certain parameter, or maybe just one page of invoices, if you're using a paginated API.
Jess Archer:
Likewise, you could potentially delete an entire collection of invoices. I don't think that's generally commonly implemented, but when you're creating an object, you are normally putting it into a collection, and the URLs normally reflect that. If you're wanting to add a new invoice to the system, you will post it to the invoices' collection, and then inside that collection, you can reference an individual one by its ID. That's when you've got invoices /1,2,3. And that's when you might want to either retrieve that one invoice, edit it, or delete it. So that's how I think of it, of REST. How does that sit with you?
Matt Stauffer:
I love it. Because you got ... and one of the things that I think is really important about REST, is that it's using the URLs to represent the identification of the resource collection, and in the individual resource. That's all a part of what you were saying before, right? It's like REST is really based around HTTP, and HTTPs, URLs, status codes, verbs... there's just some of the most important foundational elements of it.
Matt Stauffer:
So you're representing, I love that, that you point that out, by the way. If anybody doesn't know this, it's not that huge of a distinction, but it's helpful to know how they thought about it, is each of those JSON objects, or eczema objects, or whatever that you're passing around is a representation of the invoice. It's not the invoice, and that's a little bit of an arbitrary distinction, but it seemed ... it was very important, and important enough that it's literally in the name of the thing, is that the representational state transfer, it's not the actual object itself being transferred. We just take that for granted.
Matt Stauffer:
But, we've got URLs that define which thing we're interacting with. If it's slash invoices, then it's the collection of invoices. If it's slash invoices, question Mark, status equals unpaid, then it's the collection of unpaid invoices. If it's slash invoices slash 14, then it's invoice number 14. So we have defined, which resource or which resource collection that we're working with, purely through our URL. And then our verbs allows us to say, what are we doing to that collection of that resource collection.
Jess Archer:
Exactly.
Matt Stauffer:
And then what we're posting, or what we're receiving is the actual... that representation being transferred. I mean, you've got that fricking perfect. So I love that. So that's-
Jess Archer:
In-
Matt Stauffer:
... Go ahead.
Jess Archer:
... That's really important point about the URLs. The action is always in the HTTP verb, so you would never want to have to be truly restful. You wouldn't have a URL where it says, Mark has paid, for example, for an invoice. You would instead be updating the invoice record invoices /1,2,3, and changing the status, for example, property on that. That was the distinction between the more RPC, the Remote Procedure Call, where you're just...
Jess Archer:
It's kind of the distinction between the more RPC, the remote procedure call, where it's all about the action being in the URL. Instead, you're limited because you've only got the HTTP verbs that are available, but that limitation is actually quite empowering and helps you make more structured and consistent APIs.
Matt Stauffer:
Yeah.
Jess Archer:
And there's some other stuff I'd like to tell them later about ways you can improve that as well.
Matt Stauffer:
Yeah. That's great.
Matt Stauffer:
So we've got kind of a good understanding of what REST is, and we've said REST can work with XML, can work with JSON, can work with other formats, but in the Laravel world, it tends to be JSON. So we tend to do at least REST-ish, if not fully REST APIs that are transferring JSON using everything you've just described there. And there's a lot of conventions in the framework itself that actually leans you in those directions-
Jess Archer:
Definitely.
Matt Stauffer:
Where returns JSON by default and all that kind of stuff.
Matt Stauffer:
So if I were to build the simplest possible Laravel-powered REST JSON API today, could you just walk me through what some of the pieces are that I would put together for that?
Jess Archer:
Sure.
Jess Archer:
So there are a few conventions that people do depending on whether or not the application is only an O API or whether it is also a server ended app that happens to have an API. So if your Laravel app is doing both, you might want to actually create a forward slash API as part of the URL so you can namespace all the API stuff separate from the other stuff. So forward slash invoices might be the user interface for invoices, and then API slash invoices might be to get the JSON version of that.
Matt Stauffer:
Yeah.
Jess Archer:
There are some other things. We can also talk about how you can combine those.
Matt Stauffer:
Yep.
Jess Archer:
So once you've decided whether or not you want to namespace it... You might also want to put a version in the URL, you might want to put it in the header, which we can talk about later.
Jess Archer:
But once you've decided that, you basically would follow the same sort of process you would for creating a controller in Laravel. So you would do PHP artisan make: controller, the name of your controller. The convention is typically, I think, the singular name of the object, and then the word controller afterwards. So even though your URL might be posts, with a plural, or invoices, it's the invoice controller. At least that's what the documentation normally references, and I try to look to the documentation to answer those questions because I don't want to spend my time thinking about it.
Matt Stauffer:
Yep, no need to yak-shave.
Jess Archer:
So you create your controller as you would normally for a server ended app, you would add your routes as you normally would.
Jess Archer:
Now, in Laravel they've created a separate routes file for your API routes, which you can choose to use if you would like. So that would normally be, I think, routes forward slash API dot PHP. And all that file does differently from routes forward slash web dot PHP is apply different middleware, which effectively changes what kind of authentication it's going to use. APIs normally use a stateless authentication rather than stateful, which we can talk about a bit later.
Matt Stauffer:
Yeah.
Jess Archer:
So you would add your route to your API routes file, pointing it to your controller. Depending on your preference, you may want to define individual routes for your getting of the index collection, so getting all of the invoices. And then you might want to define a separate route for getting an individual invoice, like the invoices forward slash one, two, three. But Laravel also has a really handy helper called route resource, which automatically registers all the routes you need to do the seven Restful methods.
Matt Stauffer:
Yeah.
Jess Archer:
Well, it's actually kind of five, but it depends on whether or not you're building an API. If you're building an API, there's actually one called API resource that admits the two UI specific ones, which are the edit and create. Because there's update and store, which are the actual ones that do the work, not display the form.
Jess Archer:
So you can use the API resource helper. You can tell it if you only want specific methods. So maybe you only want to do the index, maybe you only want to allow people to get the invoices list and an individual invoice, but you don't want them to update them. So you can tell it to only register the index and show methods of that.
Jess Archer:
Now, when you've got your controller, if you use Laravel's scaffolding to create an API resource controller... So there's a little flag. When you say PHP artisan make: controller, you can tell it that it's an API controller, you can tell that it's a resource controller. If you tell it it's both, it'll give you the five methods rather than the full seven. And if you're using the route helper, it'll automatically wire it all up together. So it's really little code at all. And if you tell it which model you're building it for, it'll even type that in the controller, so it'll automatically through route model binding... I can't remember if we've already talked about it on the podcast, but-
Matt Stauffer:
Yes, we did talk about route model binding.
Jess Archer:
Route model binding. So it'll, if you hit the get route, automatically give you the instance of the object based on the ID using the conventions in the URL. So your get method, which I think they... Yes, the show method automatically has the invoice that you're accessing ready and available to do whatever you need to do with it, to display it.
Jess Archer:
And the simplest form of that, you may just actually go return invoice and Laravel will automatically go, "Oh, you're returning a model from a controller. I will serialize that to JSON for you." And it will automatically take the model's array form, which is basically all of the visible properties, plus any accesses you've added or upended as they call it, and output it for you. So that's kind of the most basic version of that.
Jess Archer:
When you want to throw in things like auth there's little, extra steps you need to take. And if you want to change the shape of your response in different ways, maybe you want to nest things under a data key to add pagination and other bits of metadata to the top level, there's all these other things you can add on later to take it further, and flesh it out, and make it more potentially useful, depending on your application.
Matt Stauffer:
Yep. That's perfect. But if I wanted to literally just say, "No worries about the headers. No worries about all this customization." I just wanted the fastest nastiest possible API you possibly could, I would basically do the API resource thing and routes, I would make this API and resource controller, it would have the show method type hinted. And so, I would literally just go into each of those methods, and the index one would just say, return invoice, colon, colon, all. Right? And it would cast it into JSON.
Jess Archer:
Every single invoice, yep.
Matt Stauffer:
Yeah. And then, for show, it would be just return the invoice, of course, store, and delete, and edit. You'd actually have to do some processing of the user input, and then you'd probably return some simple JSON, or something like that. And then, you're up and running.
Jess Archer:
Yeah.
Matt Stauffer:
So what is the next step to make it less nasty? You just mentioned probably about five things that we could talk about with her.
Jess Archer:
Yeah, so-
Matt Stauffer:
Where does your brain go next?
Jess Archer:
Well, I guess auth is probably the first thing to consider. I mean, if you're dealing with invoices, you probably don't want them to be publicly accessible.
Matt Stauffer:
Right.
Jess Archer:
And maybe you're not actually dealing with all invoices, you're dealing with the logged in users' invoices.
Matt Stauffer:
Right.
Jess Archer:
So you don't want to return some of the customer's invoices. You want to return only the invoices that belong to the logged in user.
Matt Stauffer:
Right.
Jess Archer:
So in those situations, we use authentication and authorization. So authentication is probably the best place to start. The difference between authentication and authorization in case people aren't quite clear, authentication is confirming that you are who you say you are, and authorization is saying, "Can you do what you want to do?"
Matt Stauffer:
Yep.
Jess Archer:
So starting with authentication, it's to make sure that you are actually a legitimate user of the platform. It's not yet concerned about what your roles and permissions are yet. It's just, are you a valid user?
Matt Stauffer:
Yeah.
Jess Archer:
So in Laravel, we've got quite a few different options for auth, depending on what kind of API you're building.
Jess Archer:
Just to quickly back up a little bit, you might want to create APIs for your first party applications, but you might be creating third-party APIs that other people can interact with to get information out. Most big companies tend to have an API, like Facebook has APIs, YouTube has APIs, Twitter has APIs that allow third parties to do cool stuff with their data effectively. You could make your own clients for it, you could pull information out to do reporting on it, anything. The possibilities are endless. What created web 2.0 was APIs, and all of a sudden these monolith services... You could actually build cool things to interact with them.
Jess Archer:
So, depending on what kind of API you're building would affect what kind of auth you want to use. I think the most common APIs I tend to build are APIs that will be consumed by an SPA, which is a single page application. So that's where you've got the front end, or user interface of your code, is all running in Java script on one single page load of the web browser, and as you click through the interface, it's not actually doing a full browser page load. It's all doing it within the browser. So I think most people are familiar with these interfaces because when you click something, you don't actually feel like it's a webpage. It feels more like an application.
Matt Stauffer:
Yeah.
Jess Archer:
So most of the APIs I build are first party APIs to be consumed by an SPA.
Matt Stauffer:
Yeah.
Jess Archer:
So in those cases, Laravel Sanctum is probably the best choice for that. For a first party API, you can actually make them...
Jess Archer:
So let's firstly talk about the difference between a stateful and stateless API. So with a... Stateful, in general, means that on the server, it's maintaining some form of state about the user's session. So when you log into a normal server ended app with Laravel, it starts a session, and this might be stored in a file, it might be stored in Redis, but there's a cookie that references the idea of that session that your browser holds on to. So you log in one time, a session is created, and then from every request from then on, you don't have to log in again because you're just [inaudible]. You're saying, "I'm still on this session. I'm The only one that knows this session." And so, the server's maintaining that logged in state.
Jess Archer:
Most APIs are stateless. So every single request, you've got to authenticate with as if it was the first request.
Matt Stauffer:
Right.
Jess Archer:
So whether you're using token-based authentication, or OAuth, any of those things, they're all generally stateless. There's nothing on the server that remembers, "Oh, you're logged in." It's just, every single time the request comes in. It's like, "Give me your credentials."
Matt Stauffer:
Yeah. Yeah.
Jess Archer:
Yeah. So with a first party app, though, on an SPA, you can actually still use a stateful API. You can still use sessions, you can still use cookies because...
Jess Archer:
This is getting maybe a little bit off topic, but cookies, I still think, are the best way to transfer tokens when possible. There's some restrictions in terms of if you're using different domain names, but if you're on the same domain name and you can actually pass a cookie around, cookies are the safest, because you can make them so that your JavaScript cannot see it, but the browser will automatically pass it for you with every single request.
Matt Stauffer:
Right. Yeah.
Jess Archer:
So if you get some malicious JavaScript code running through, an XSS vulnerability, it can't get the token and make its own requests.
Jess Archer:
So, yeah. I like cookies where possible. I think Sanctum implements that by default, if you use the SPA authentication and... Yeah. You don't, generally, then have to worry too much about passing through authentication and all your headers.
Matt Stauffer:
Yeah.
Jess Archer:
But then there's also OAuth you might want to use. That's probably a bit too much to dig into in the time that we've got, because OAuth has so many different types of ways you can use it. I generally find though that OAuth is best for third parties and, most commonly, for when there's two companies, and they have a common user, and company B wants their user to use something on company A's website. So the best example maybe people are familiar with is, when you do social sign-in with GitHub or Facebook, when you let your app... Basically, you're allowing your users to authenticate another app on its behalf. That's really confusing to say. I don't really know how to explain this elegantly.
Matt Stauffer:
But so, yeah. So that's, that's a good point.
Matt Stauffer:
So let's say that I was building... I mean, I've built like ten apps that are all authenticated with GitHub. By setting up OAuth authentication on GitHub, it allows me as a client of this GitHub application to allow my customers, who are also their customers, like you're saying, to click a button and say, "I want you to share a little bit of information back with Matt's application.
Jess Archer:
That's perfect.
Matt Stauffer:
Yeah. And that information being shared happens over OAuth.
Jess Archer:
Yeah.
Matt Stauffer:
So I had to register as a client, they had to go sign in to GitHub, prove who they are, and then, they had to basically approve giving that information over to me.
Jess Archer:
Exactly. It's giving a way for you to allow your users to give their data to third parties through a secure method that allows them some level of access control and revocability and all those important things.
Matt Stauffer:
Powerful and complicated.
Jess Archer:
Yeah, it's very powerful. Yeah, it's a nightmare. It was one of those things like... When I first started dealing with OAuth, I didn't understand it. I didn't see the point of it, and even now still, it's not my go-to choice. I will tend to use token-based authentication where possible, things like JWTs, which we can talk about later if we want to. And yeah. There's other OAuth types for machine to machine authentication, but again, I think tokens generally can do the job.
Matt Stauffer:
Yeah. I would agree with you on that. OAuth is probably the most robust and powerful option. It's also the most complicated. We do have Passport, which is a Laravel tool that makes it a lot easier to spin up your own OAuth, which is wonderful because I've spun up my own OAuth servers without Passport and with Passport, and Passport makes it way easier.
Matt Stauffer:
But just because we have that tool does not mean that OAuth is the right fit. And especially for people who are just getting started, like Jess said, the majority of the time that you're building APIs, you're building APIs for internal JavaScript consumption, whether it's an SPA or it's just individual JavaScript, or Vue, or React components that need a full amount of data and want to interact with it.
Matt Stauffer:
So start with the simplest possible thing. I love what Jess said. You know? Here, it's just like, stick with tokens. If you are a Laravel person, stick with Sanctum. Sanctum was designed to make it easy for you to use your APIs in your internal code without having to worry about all the complexity of OAuth. The whole reason it exists is just to allow you to use statefulness, allow you to use sessions, allow you use the default Laravel auth, and just have it authenticate you against you against your API.
Jess Archer:
Exactly. I don't think I've actually ever created an app where I needed the users of that app to be able to grant permission to their data to a third party. I've definitely created applications that take advantage of someone else providing that mechanism, but I've never created something that needs to provide it to someone else.
Matt Stauffer:
Yeah. I have, but it's been infrequent. Yeah. It's very, very infrequent.
Jess Archer:
Yeah.
Matt Stauffer:
That's the thing. If you're new to this, just don't do it. Just don't do it until you're absolutely sure it's the thing you need to do, and that's not going to be at the beginning of your journey.
Jess Archer:
It's good to learn about it so that you know that it is a tool available in your toolbox if you run into that problem, but don't go deep on it until you need to. But definitely look into the different grant types of OAuth, just so you know what's available, because there were some that were designed for first-party auth, but they tended to be quite problematic because you had client secrets, which you couldn't keep secret in a JavaScript based application.
Matt Stauffer:
Yep.
Jess Archer:
Even the machine to machine stuff I think. Yeah. Generally, tokens are probably easier for most situations. It does allow ways to revoke things and all that, but yeah.
Matt Stauffer:
Yeah, it's robust.
Jess Archer:
Yeah. You can still do it with tokens anyway. Yeah.
Matt Stauffer:
Yeah. Totally agree. Okay. So if we were to add auth, the first thing we would just say is, just go use Sanctum, learn Sanctum.
Jess Archer:
Yep.
Matt Stauffer:
We wish we had more time in this podcast, but we don't, so go learn Sanctum, and it's going to just integrate really, really easily. So once you've got your really rudimentary thing where you're just returning models, and it's authenticated through Sanctum, and let's just say we got authorization out of the way as well because you use Laravel's built in ACL.
Matt Stauffer:
And again, that's not the topic of this one, but you all have heard us talk about this access control layer before. I can't remember which episode, but we talked about it. It was the one with Joseph Silber about authorization and authentication. So, yeah. So in that one, we talked about authorization. If you haven't heard it, go check that one out.
Matt Stauffer:
So let's assume you've got your authentication and you've got your authorization built in. What's next?
Jess Archer:
Okay. So if we go back to the controller, if we go back to that index method that was returning invoices all, now inside that controller, if you've set up your auth, you'll actually have an authenticated user at that point. So instead of returning invoices all, if you've set up the relationships so that your user can have many invoices, you might instead return the authenticated users' invoices, which might just be using the request helper to get the currently authenticated user and then accessing the invoice's relationship on that. And then, that will only return the invoices that belong to the person that's logged in, as opposed to every invoice in the entire system.
Jess Archer:
Again, it depends what kind of thing you're building as to whether or not you want that, but that's something that's good to know. Likewise, when you're doing... This is probably something that's actually really easy to forget. If we look at our existing get method that we had before... Sorry, the show method for doing the get request. If we're just returning the type hinted invoice and not actually making sure that the logged in user has access to it, then you can access anything by its ID. So you can do what they call an enumeration attack, where you go, "Oh, my invoice is 123. I'm going to try 124, and see if I get someone else's."
Matt Stauffer:
Yep.
Jess Archer:
So you want to make sure you've got some link in there. There's a few ways to do it with Laravel that I think we've talked about.
Matt Stauffer:
Yeah.
Jess Archer:
But make sure that the user owns the invoice that you're returning, is kind of the takeaway there.
Matt Stauffer:
There's some helpers in terms of authorization where, if you're using that rock model binding, the simplest one... Well, I don't know if it's the simplest, but the most convenient one is to just say, "Don't authorize the user against the route," and there's actually a canned middleware where you can decide whether or not they can even see it based on that ID, but it doesn't work on all of them. Right? It doesn't work on the index, because the index... You're still going to have to do that same work you did. So even-
Jess Archer:
Well, the thing with the index is, if you're only returning what the user has access to, there's no way for them to do anything else. They can't pass in a different user's ID. It's only ever going to return what belongs to them. But if you're using policies, there is a view any kind of policy helper that you can do a little bits and pieces with, but the simplest thing for me, or my favorite way as a policy, anytime you're dealing with a model or an object. And in most cases it might just be... You're returning true if the invoice ID is equal to the user ID.
Matt Stauffer:
Yeah. Or the invoice user ID.
Jess Archer:
But again, it depends on what you're building. Yes. The invoice user ID. Sorry. Yeah. Good point. Yeah. That would have been a bug right there.
Matt Stauffer:
I think it's safe to say if we're trying to say code out loud where we're allowed to sneak some bugs in it accidentally.
Jess Archer:
Yeah, cool.
Matt Stauffer:
Okay. So we've got authorization, we've got authentication. We've got that same thing you're saying, where we're scoping the data back down. Where do we go from there? Is it transformation? Because I know we can talk about transformers... Yeah.
Jess Archer:
There's two things I really want to hit on. I think the first one I want to hit on is nested resources, because I really like these quite a lot. So, a nested resource is basically where you might have... Say you've got invoices again, to use that as an example, you might have payments on an invoice. So if you've got a relationship, normally this is a good signal that you might actually have a nested controller.
Matt Stauffer:
Oh, yeah. Yeah.
Jess Archer:
So if you've got an invoice, then it can have multiple payments. Some people attempted to put all of their logic on the invoice controller around those payments, and they'll end up creating custom method names on there and, potentially, even custom URL things to deal with that. But I find that the thing that creates the most nice to work with APIs and the thing that, to me, adheres most close;y to the spirit of REST is to nest those resources.
Jess Archer:
So, you might have invoices slash one, two, three slash payments. And if you do a get request to that, you're going to get every single payment scoped to that invoice. And again, you've got to make sure that the user has access to that invoice because in that case, even though it's an index method, they are passing in an invoice ID. So you need to make sure it's valid for that.
Jess Archer:
And likewise, if you want to make a payment, you might actually be doing a post request to that payment's collection. And if you want to see information about an individual payment, it might be invoices slash one, two, three slash payments slash four, five, six. Yeah. And I get requests that might get information about that, and maybe if you need to update the payment, you might do a put or a patch.
Matt Stauffer:
Yeah.
Jess Archer:
Who knows?
Matt Stauffer:
Yeah. I love that.
Jess Archer:
It's important to know that you don't need to implement every single method to be Restful. If it doesn't make sense in your business domain to edit a payment, then just don't have the route, and the method, and all that stuff for it, and that will return either a 404 or a 405 method model ad depending on if the URL exists. And I could probably talk for ages about status codes and the appropriate ones, but... So that's nested resources. You can define them in Laravel using conventional helpers that you can kind of just say, invoices dot payments, and it'll automatically create the routes and know to put the forward slash and then the invoice ID and all that sort of stuff in place for you.
Jess Archer:
And the controller you create for that, if you scaffold it using Laravel's tools, the index method will actually have a type hinted instance of the parent. So in this case, the index method will actually get typed into it with the invoice that you're accessing. So you can then just go return invoice payments, as long as the user can access the payments, of course. And to me, that creates the best Restful API, is when they're kind of nested in this way that makes sense.
Jess Archer:
If you needed to access all payments, regardless of invoices, you could create a separate route for just payments that's not scoped to invoices, but generally, if you're doing things that are scoped, I really liked nested resources.
Matt Stauffer:
I love that.
Jess Archer:
There is one patent that some people use where, if they're getting the nested resources and they're getting the index of them, it'll be invoice forward slash one, two, three slash payments. But if they only want to access an individual payment, they will flatten it, so it's just payment slash and then the number. And Laravel actually has with its route definition, the route help, it will actually let you define whether or not you want to do that flattening. I think they might even call it flattening.
Jess Archer:
But I still prefer to keep everything nested for whatever reason.
Matt Stauffer:
Me too.
Jess Archer:
I mean, you can end up with some deep nesting of, if the payments have statuses and multiple-
Matt Stauffer:
Right. Yeah.
Jess Archer:
Yeah. You can get too long. And if you're using UUIDs instead of numeric IDs, your URLs can get pretty unwieldy and just look ugly. And one of the things I like about REST with a numeric ID is that the URL communicates exactly what you're going to get and you can see it really, really easily. And of course, your UIDs give you the same thing, but it just kind of obfuscates the important bits.
Matt Stauffer:
Yeah. Yeah, and it's... I was going to say, because the good news is that usually when you're building your URLs like this, it tends to be for APIs. Right? And so, if it tends to be for an API you're a little bit less worried about the consumer actually ever seeing it, but still there's this developer experience, and if you've got eight segments of indenting, every other of which is a 16 character long or whatever UID or something like that, it does get a little bit overwhelming. But the nice thing is, even if you find yourself in that situation in REST, you're going to be able to parse through what's going on. Right?
Jess Archer:
Yeah, exactly.
Matt Stauffer:
Because it's collection, ID, collection, ID, collection, ID, collection, or whatever. In the end, it's really going to be this very reasonable and rational way of thinking, which is discoverable. Right? I forget what the word that you use, but it's easy for... It's intuitive. It's easy for someone who comes along to understand what's going on, even if they've never worked in the system.
Jess Archer:
Exactly. You want to be able to make an educated guess and be right. And that's... Generally what I strive for with any API is, once you get a feel for what it is... I mean, there's times in Laravel where I think, "I wonder if this exists," and I just try it and it-
Matt Stauffer:
It works.
Jess Archer:
And it's there. And that's... One of the things I love about it is that now that I've kind of got my head fits the way Laravel works, I can make those intuitive guesses and most of the time be right. And if I'm not right, generally that means this might be a good PR.
Matt Stauffer:
Right.Yeah. Yeah. If I guessed it this way, then I'm probably not the first person to have done so.
Jess Archer:
Exactly. So, that's nested resources.
Jess Archer:
In terms of returning responses, I think we want to talk a little bit about transformation. The most common way... Well, actually there's a few ways that are in Laravel. So if you are just returning the model, Laravel will automatically convert it into the serialized version of that under the hood. I think it uses the two array helper to get the array form of the model, which it then converts to JSON. You can use little things on the model to tweak what happens there, so you can append extra-
Jess Archer:
In the model to tweak what happens there, so you can append extra fields if you've got things that aren't actual database fields. So you've got some accesses that are creating a virtual field. So maybe you've got a first name and a last name column in the database, but in your API response, you just want it to return the full name. You might have an accessor that returns full name, and you can append that accessor to the models array form, or JSON form. And you can also hide things. And that's one of the main reasons for the hidden thing Laravel used to say, "Oh never return the password in the serialized form of this," even though it's encrypted, it's still not good to give people that. So that's one way of transforming it. You can override the two array method on your model and return any array you want, accessing whatever properties you want.
Jess Archer:
You can even pull in properties from a child or a parent relationship if you wanted to, to create whatever representation you think is best for that model, it doesn't have to map to your database structure. Oftentimes yeah, there's things that make sense in a relational database that when you're talking about the object as a whole to like the consumer it might not even have a database table associated with it. Or the database table might have a name that's using Louisville's convention of like for many to many relationships where it's the model and the score model, and you might actually have a different name for that like subscriptions. I think this example, Adam Ivan uses. So you can customize it in the models to array helper, but the other most common way in Laravel is to use API resources, which are an extra class that Laravel gives you.
Jess Archer:
Basically lets you define the JSON version of a model, how it will be represented, including any relationships. So you may, for example, always want to get all the payments with an invoice and you don't want to necessarily have to hit the invoices show method and then also hit the payments route to also get the payments. So you may want to actually make it so your invoices route always returns all of the payments for the invoice in that same request, like in a nested payments and then an array of all the payments in there. So you can define that in an API resource, you can define it in the two array helper as well. There's so many ways of solving these problems, but it just lets you have more control over exactly what response you're returning. Maybe you want to format your dates in a different format for your API response.
Jess Archer:
You can kind of tweak that. Yes. You know you'll normally have a carbon instance and it'll normally be serialized in this format, but for this case you need it to be using a different format. So in your API resource you might say the date is this. You might have been change the name of it, you might... For your API needs to be created at instead of updated that because you're integrating with some of the third party that doesn't adhere to Laravel's conventions. Who knows like there's so many reasons to transform. You have to transform what your model is represented as in JSON.
Matt Stauffer:
Yeah.
Jess Archer:
So yeah.
Matt Stauffer:
And I think one of the things I really... So I think API resources are fantastic and I'm a very big fan of transformation in general. And the reason I don't tend to use the first ones you described, I'm glad you introduced them. But it's because there I think there's two big issues with it. Well, there's more than two, but one of them being that it's the gets hidden away in some of the model methods.
Jess Archer:
It can do. Yeah.
Matt Stauffer:
Yeah. And also another one being that sometimes you want things, like if you make a customization on the model itself, then that will customize the way it returns to array always. But sometimes you want it to change one way and in one context and these API resources are very narrowly scoped. This is how it's supposed to have in this one context. And you can make more than one API resource for the same model.
Jess Archer:
Exactly.
Matt Stauffer:
But one of the things so having built multiple custom transformers myself and seeing other people tightened to it. One of the things I love is that API resources, A, they handle nesting of resources within collections, without you having to do any extra work. They just give you that free. And then B there's a lot of little helpers where you get to do conditional things. And I can't remember what the syntax is, but basically inline as you're defining the return of the... Yeah, you can say only show this if you have E reloaded this particular piece of the data before parsing this transformer. And so it gives you this really ability to do these much more robust APIs without even knowing ahead of time that you're going to need to, or how to do it if you did need to. Right?
Jess Archer:
Exactly.
Matt Stauffer:
It's another one of those things where you don't even know you need it, but when you need it, it's just there for you rather than you now having to completely rewrite your custom transformer.
Jess Archer:
Exactly. I think there's an example that really helps sell it, which I think is if you've got a resource that looks different from my user vs an admin, an admin might actually be able to see more pieces on there. You could do in the controller check if they're an admin, you could do it in the resource. There's two ways that you can think about it. You can use a conditional in the one resource and say, "If they're an admin show, these fields," or you could create two separate resources, have the admin representation and the use of representation. And both are valid-
Matt Stauffer:
Yeah.
Jess Archer:
But people will have different preferences. And I quite like the idea of having an admin representation of it. There is potentially some double-handling. If you add a new field, you've got to remember to add it to both if it's supposed to be there, but it's less complex because there's no conditionals that are polluting the whole thing and muddying up what it might actually be so.
Matt Stauffer:
Yeah. And you know, this doesn't always work, but sometimes you can also have the admin one extend the user one.
Jess Archer:
This is true, yeah.
Matt Stauffer:
And then you basically just use the parent. And so you get the up to the user one, then you append stuff onto it for the admin. So yeah. There's just so much you could do with them. Right. They're just such powerful tools. So yeah. Try API resources people they're vendors sold value.
Jess Archer:
Yeah. The other thing they do is when you are using them to provide a collection, they can automatically give you pagination and they give you pagination in a way that's kind of like, it's true to like the JSON:API kind of way of doing it. So it adds the URLs and everything to know where to find the next page and what page you're on. And it uses just a standard convention for representing that information. So you, haven't got to make up your own. I always find that the less decisions I have to spend on those things, I can save my decision budget for things that can actually match my business logic. Yeah.
Matt Stauffer:
Exactly.
Jess Archer:
Not what convention I'm using. That's what the convention for is to save my decision budget.
Matt Stauffer:
Yeah. I love it. I agree. And was a wonderful surprise when I started doing all that research into REST APIs and just discovered the Laravel's native pagination response in API resources was exactly what all the front end libraries needed. Exactly what the spec was. And I was like, "That's just a moment of joy." I appreciated that.
Jess Archer:
Yeah. And then you can bolt on like Sparsely query builder one, that adds a few extra bits and pieces that are for sorting, for example.
Matt Stauffer:
Yeah.
Jess Archer:
That also uses the same convention. One of the coolest things about that, small side topic, whenever I used to do pagination, I always used to use two fields. I'd have the sort column and the sort direction as two separate inputs. And the thing I love about JSON:API, and the thing that Sparsely implemented was a single parameter and a minus sign in front is descending. And having just one column is just so much nicer, but you do need to still work with that and parse it apart, which can be a bit of a pain to implement. But if you've got libraries that have struck that it's a much more pleasurable thing to work with I find.
Matt Stauffer:
All right. That was literally the first thing that sold me on JSON:API, was that it finally taught me how to do that sorting. Because you'd seen sort by an order or direction and sort, or whatever, and everyone had a different way of doing it. And you got these two columns and now it's just like, "Oh, it's just a negative at the beginning or not. Or minus at the beginning, or no minus at the beginning." Why didn't I think of that?
Jess Archer:
Yeah. It's much more elegant and simple and yeah. And it's an invention that I can choose rather than making it my own.
Matt Stauffer:
Yeah. So you said there was two more things. One of them was transforming. Was there another one or do we already get to the other?
Jess Archer:
So the other one was the nested-
Matt Stauffer:
Right, right, right. That's the...
Jess Archer:
Yeah.
Matt Stauffer:
Okay. So we've covered a lot of the big things. I know that we haven't covered all the things that you said we might talk about later, but I wasn't typing them down as you said them. Are there any other kind of key things before we start moving on and maybe some common challenges and gotchas that you think people should really understand about what it's like day-to-day Laravel API?
Jess Archer:
I mean, one of the things that I probably like the resources that I refer to all the time is the Wikipedia page on HTTP status codes. There are a lot of-
Matt Stauffer:
Yeah, let's talk about them.
Jess Archer:
Yeah. So there's a lot of different websites that tell you about all the status codes. There's some that kind of a specifically dealing with REST. But to be honest, I find the Wikipedia page one is perfect. So for anyone that doesn't know the status codes are what defines the response that your server is returning to the client. So the common one being 404, being the thing wasn't found as the one most people know. A successful response is 200, but there are so many other status codes and they're actually quite meaningful. And some of them even have different implications on how things might be caged and proxied, and even just creating a richer API. So a great example is 201 means created. So returning 201 when you are doing a post is a nice way to say that something was created. Likewise if you're doing a post that creates something, but that thing doesn't actually get created at that time, say it goes into a queue to get processed later.
Jess Archer:
There's another one which is 202, which is accepted. So that's kind of, you're saying "I've accepted it. I'm going to work on it, but I haven't yet done it yet."
Matt Stauffer:
Yeah.
Jess Archer:
And the response for a 202 might be different than a 201, because 201 you would typically return the resource that has been created. But the 202 accepted, you might not have created it yet.
Matt Stauffer:
Yeah.
Jess Archer:
There's another one that's handy in the 200s. So anything that starts with like a two, the 200 series, they're all the success happy path onces.
Matt Stauffer:
Yeah, exactly.
Jess Archer:
204 Is a good one. It's no content and you're not allowed to return anything in the body of the response. If you return a 204, and the thing this is the one I use this for all the time is deleting. Once I've deleted in a resource-
Matt Stauffer:
Interesting.
Jess Archer:
There is nothing to return. So I like a 204 for that. It's saying that it was successful and there is nothing to return. Yeah.
Matt Stauffer:
Yeah. And that's cool because-
Jess Archer:
So I tend to use that as a signal.
Matt Stauffer:
These codes are standardized. And so like the number of times we have yak shaved over what what keys should we have in our JSON responses? Should there be a status that has a message and then a successful that is true or false and then maybe a description or whatever. And with these, it's just kind of like, "Hey, if it's 204 you don't need to know anything else. You send it to me, delete command, you got a 204 back. It's deleted. Cool." And you can handle how to process that in your own-
Jess Archer:
Exactly.
Matt Stauffer:
Yeah I love that.
Jess Archer:
A hundred percent. And then you've got like the three hundreds, which are mostly to do with redirects. But if you choose a temporary redirect versus a permanent redirect that can have caching implications. So you want to kind of make sure you choose the right one for your application. The 400 series, 400 on up to 499 are the client errors. So that's generally when the client who's consuming a API has done something wrong in some sort of a way. So the 400 is the generic bad request. I don't know how to describe it any better way. Then you've got the 401 and the 403 that deal with authentication. And the 401 is kind of subtly different in that it's saying, "You need to authenticate before I can give this to you." And the 403 is basically saying, "You're forbidden and you've already tried to authenticate."
Jess Archer:
Yeah. Maybe you authenticated and you've got your password wrong. Well, maybe you're authenticated, but you don't have permission. So there's a subtle difference. And the way that browsers will handle this can also potentially be different. 404 Again is not found, 409 conflict is a really interesting one. If you do something where two people edit the same record, or there's just some reason you can't update something because there's been a conflict. Yeah, 409 is kind of cool. 422 Is a common in Laravel with the unprocessable entity, which Laravel is kind of... I don't know if it was ever meant to be used for necessarily for validation, but I think Laravel kind of pioneered that and it's become really popular. I don't know if Laravel was the first one to do it, but I feel like they're the main one to use 422s.
Matt Stauffer:
I think so because I remember reading a whole thread about it and people are like, "In this framework, Laravel did it and blah, blah, blah, blah." And I was like, "Oh cool, look at us being all famous.
Jess Archer:
Yeah. It existed before, unprocessable entity, but I think the idea of using it as a validation error status code was, yeah, it was potentially something Laravel did. And then the 500 ones are the server errors. They're generally the unexpected things. It's very rare that I will deliberately return a 500 type error. It's like, if something on my end has gone wrong it's a 500, there are some that mean different things. Like if your site is down for maintenance, I think five or three is the common one to use.
Matt Stauffer:
Sounds right but I don't remember.
Jess Archer:
Yeah. They can all have implications on caching with proxies and all that sort of stuff. And the same with the HTTP verbs. Another thing I wanted to touch on was like when to use different types and the concept of item potents, which is one of my favorite words. Which basically means when you do an action, it has a side effect. But every time you repeat that action, the side effect is the same as the first time it happened. So in HTTP or put in a patch request as opposed to the item potent. So when you edit a record, if I update an invoice to say that it's paid, if I do that the first time it changes it to paid the second time I do it, it doesn't actually change anything. Nothing else on a server is different. I can run it a hundred times it's the same result every time after the first time.
Jess Archer:
Null impotent, I don't know how to pronounce these properly, is when there's no side effects. So things like a get request. A get request generally shouldn't do anything on your database or on your server. It shouldn't actually have any side effects. Get requests are often cached, so you shouldn't expect that every time someone does a get request it might actually reach your server. It might be done in the middle. And also get request generally are protected by a CSRF protection. So if you're using a get request to update something in your database, it's potentially a security vulnerability. And then the post ones, there's not really a word that I hear people for like null impotent and item potent. But I think omnipotent is really probably the correct word to use for a post request.
Jess Archer:
And that's when every time you do the action, the side effect will happen again. So if you are posting an invoice to an invoices collection, you post this data about the invoice and then you do it again, you'll have a second invoice with the same data as the first one, with a different ID probably. So yeah, that's kind of the difference there. And the subtle difference, I think, between putting patches around whether or not you're putting in a brand new copy of it to the same ID though, or whether you're just patching just the status, in Laravel I don't think there's much of a distinction and you can pretty much... I think people do whatever they want. It's just generally known this is the one for editing.
Matt Stauffer:
Yes, exactly. And it's usually thrown around putting patch as almost if it's a one word because we seldom differentiate them so.
Jess Archer:
Exactly so.
Matt Stauffer:
Yeah.
Jess Archer:
And I think for most practical purposes, it doesn't really matter for those between putting patch you're doing at least in most Laravel applications. So understanding status codes, I think is really important to return the most appropriate one for the situation and to not get too creative with them either. If you return a 404, it ideally should be because the resource in the URL is not found. If your user... If someone's looking in the user's not found, you probably wouldn't return a 404 for that because the URL for login-
Matt Stauffer:
Yeah. It's still working.
Jess Archer:
Yeah. The URL exists that path exists, but you've done something else to it that's not valid. So in that case the 401, 403 is more appropriate. So 404 I would encourage people to really save it for when the model that's directly referenced in the URL. If you'll pull in other models and they're not found returning 404 doesn't always make sense. And that can actually create things that are confusing because you're like "That's in there. That's in the database."
Matt Stauffer:
"That thing's deffinitely there." Yeah.
Jess Archer:
Yeah. But it's because some middleware is checking whether you've got a subscription to that and you're using find or fail instead of find. And not handling it with something else that's more descriptive of the problem. So, I think that's a pretty good distinction. And the only other thing was to talk about was the headers.
Matt Stauffer:
Okay.
Jess Archer:
And the two main ones are probably... Sorry-
Matt Stauffer:
Can we pause for just a second?
Jess Archer:
Yes.
Matt Stauffer:
I want to do a real quick recap in the last two that you just said-
Jess Archer:
Go for it.
Matt Stauffer:
Because I think... So we talked about these status codes. So 200 means "Yay success."
Jess Archer:
All good.
Matt Stauffer:
300 "Means go away, go somewhere else." Right? Redirect. 400 Means you're bad. Right?
Jess Archer:
Yeah.
Matt Stauffer:
You as a user end up something, and then 500 means "My bad." My server is messed up in some way, shape or form. Right?
Jess Archer:
Yeah.
Matt Stauffer:
And just to a new programmer, if you ever see a 500 error on your server, the first thing in your mind should be, "I wonder how I can find the stack trace?" Because if you've got a 500 error on a layer of application, 99 times out of a hundred, that's... You're only seeing the 500 plainly because your debugging is turned off. It's either because you're on production or because your local app, it doesn't have this app_underscore debug environment variable set to true. So if you can, if it's not in production, just set that thing to true and what you should get instead of just like a blank 500 error page is you should get a full stack trace because there's something wrong in the server. And in PHP, it's almost always just like a PHP error, there's a syntax error or an exception that got thrown or something like that that didn't get caught.
Matt Stauffer:
And so there Laravel is going to do this thing where it just says, "Hey, we're in production. I don't want to show these people the problem. I'm just going to tell them, Hey, there's a 500 error." So for you as a new programmer, if you see a 500 error, what you should think is something's wrong in my code, somehow somewhere, some shape. So.
Jess Archer:
A hundred percent, I totally agree. I think generally a 400 error wouldn't actually trigger an exception and be logged or anything. But a 500 error is normal. I mean, unless you're using like maintenance mode or something, 500 errors normally yeah, there's actually an error. It should have been logged. There'll be an exception, all that sort of stuff.
Matt Stauffer:
Yeah. And then, so the other one was the verbs. So get means, show me a thing. And it shouldn't have any impacts. I love the point you made about cachable. It should be able to be cached. And so imagine that all of your, whatever happens in any of your methods that are meant to be called by get, you should believe that an end user may not actually trigger those methods being called because of the cache. Right? So the first user, every hour triggers that method and then the remaining users for the remainder of that hour, just get the cache delivered by Varnish or whatever else. And so that's a really great kind of reason why you were saying that. And they could. Even if you have a cash setup, it's a good way to think about it. Get requests can be cached and they're not secure.
Matt Stauffer:
So, and if anyone's not familiar with CSRF it's cross site request forgery where basically another site pretends to be you and sends a request to your server. And so like Jess was saying, Laravel is going to protect your non get routes from cross site request forge use. They're not going to protect your get routes, which is why your get routes shouldn't be doing anything that could actually potentially get hacked. Okay. So we've got get, which is for showing stuff. We've got post, which is for creating stuff. We've got delete, which is for deleting stuff. And we got put in patch, which were for editing stuff. Patch is, I think I see more commonly being basically "Here's an ID and here's the fields I want to change." Right?
Jess Archer:
Yeah.
Matt Stauffer:
Whereas I think put, seems a little bit less common, which it tends to be, " Here's an ID and here's the entire replacement of that resource."
Jess Archer:
Agreed yeah.
Matt Stauffer:
So if all else fails and you need to make an edit, do a patch and along with the patch, you basically are going to be patching to the ID, to the URL, which contains the ID. And so then you've already sent the idea along. So now all you need to pass along is what things do you want to be different? And you don't have to... Anything hasn't changed, you don't have to send a log to a patch. So that's the most common edit. Okay, there is one more, which is options. And options-
Jess Archer:
There's also a few...there's also head but-
Matt Stauffer:
Yeah, so I meant to say there's quite a few more, but usually the only other one you will see is options because a lot of JavaScript frameworks... Oh, so yeah. Let's talk JavaScript for a second. One of the reasons why these HTTP status codes are wonderful is because they do such a great job of communicating clearly using a standard, why something's going on. But one of the other reasons is that lots of existing packages, whether JavaScript or PHP have automatic built in responses when they get the certain HTTP status codes that you may not know are even there.
Jess Archer:
True.
Matt Stauffer:
And so for example, a lot of these things, if they send in something and they get a certain type of error, they'll actually have a conditional inside the JavaScript package or whatever that says, "Oh, this failed instantly parse it to the error handler instead of the whatever handlers. So if you've ever used like Axios and you're doing like a request and you can do the success handler or the error handler, it knows it's an error based on the HTTP status code.
Jess Archer:
Exactly.
Matt Stauffer:
And so you can be passing this useful information onto the consumers who may not even know that you did it that way, by just changing the HTTP status code that you're giving them back. So there's so much value that comes out of using those. So, but talking about the end points... So talking about options for a second could you just, and if you don't have the answer for this, that's fine I'll throw one out. But when would somebody commonly see options? Because I see it a lot in JavaScript. Is that kind of, you're thinking of it too? Are they trying to fetch ahead of time?
Jess Archer:
Yeah. Options generally I've seen a lot more lately since cause became a thing and it's normally sent as they call it a preflight request. And it's kind of just checking to see what it can do. It's basically saying what options are available to me. And generally that's when you'll get your cause arrows because it does the options request and the things like you can't do kind of anything. So that gets rejected and then it never even goes and actually makes the request that it was... The post or they get or whatever it wanted to do. So that's where I've seen it a lot more recently. You'll typically see your API requests will be in options followed by the post.
Matt Stauffer:
Yep.
Jess Archer:
This little pair of them that happens within a split second to each other and yeah that's kind of the intent of it is "What options are available to me?" It's not something I ever implement myself.
Matt Stauffer:
Same.
Jess Archer:
It's something that just kind of happens. Like the browser is doing it and Laravel is handling it effectively.
Matt Stauffer:
Yeah. So first of all, usually options is just telling you what verbs you have. Right. It's not, there's not any other option it's parsing back. Right.
Jess Archer:
I don't think so. There may be other headers-
Matt Stauffer:
Okay.
Jess Archer:
Like I said, it's not something I ever have needed to deep dive into.
Matt Stauffer:
Same here. Yeah. I've never programmed at the JavaScript side and I've never programmed in the PHP side because Laravel does it for me. But I do know that you're a hundred percent right. Which is that almost every single time I've ever seen options it's because something said, "Hey, I'm trying to send an options request. And instead of getting an options, response back, I'm getting this weird thing." And the weird thing was always a cause error of some sort. But the thing, so it was like a misdirection, right? Like it made me think and the other are the people I was helping think, "Oh, there's some options thing, which I never even programmed, I don't even understand." So it's like this. And what was in reality, it was cause. And if anybody doesn't know it's, I'd get another security thing, cross origin, request scripting or whatever, which is just another place of people potentially being able to hack you, Laravel saving your butt.
Matt Stauffer:
But if your cause is not configured correctly, then you're going to get this options error. So the simplest thing to say with options is if you see an error around options, when something is hitting your Laravel API, the first place to look is this a cause error. That's enough for me for now.
Jess Archer:
A hundred percent, yeah.
Matt Stauffer:
Yeah.
Jess Archer:
I think it's normally the browser that sends the option request. So not even the JavaScript. The browser-
Matt Stauffer:
That's right. I don't think it was the JavaScript.
Jess Archer:
Yeah. And it depends on the conditions of the request. So it really depends on if it meets certain criteria and it considers it... I think they use the word, like a complex request. Then it will be a cause request. So simple gets with no extra fancy headers often don't run into cause problems, but it's when you start doing other things that trigger it to go into cause mode. And yeah, it's something I don't know, off the top of my head, but I know that I've run into it before.
Matt Stauffer:
Yeah. Same here. All right. So I interrupted you or you were about to go into something else, but I just want to make sure we covered those ones quickly so.
Jess Archer:
So yeah. So I don't want to like take up too much of everybody's time because I could talk about this stuff for hours and hours.
Matt Stauffer:
This is good stuff though, it's good.
Jess Archer:
So the other thing is content types except headers, headers in general. The most common headers I think that I probably used in terms of implementing things myself. The accept header and the content type header. I feel like these are like a pair of headers. So the content type is what describes what the body of... Is in the message that's being sent or received. And the accept is basically what you'll send in your request to the server saying, "This is the format I will accept." So a typical web browser, I think sends like asterisk to say, "I'll accept anything." And most things will send like, "Okay, cool. I'm going to give you HTML.
Matt Stauffer:
Yeah.
Jess Archer:
I think they actually send asterisk and then comma texts...
Jess Archer:
TML. I think they actually send asterisk and then comma tech slash HTML. They use these mime types, which are always generally something slash something. So like tech slash HTML tech slash plane application slash JSON, all these different. I can never remember exactly if it's a flip slash or a backslash, but when I type it my muscle memory knows it.
Matt Stauffer:
Yes. Same here.
Jess Archer:
These can be quite powerful. You don't need to worry about them when you're just starting out. A lot of the time things will happen automatically for you in Laravel when you're sending stuff with Xes on the front end. If you're doing stuff with JavaScript, it'll normally specify the head is for you but what's really cool though, is that if your application throws an exception, say a model can't be found or something goes wrong.
Jess Archer:
Laravel's exception handler will actually customize the response depending on the accept header. So if your web browser is sending its standard, I can accept anything on my web browser then Laravel says, "Okay, cool. I'll give you the HTML error message," and if you had got debug mode on, it'll have the stack trace. If not, it'll just be like whoops, something went wrong, whatever they're using these days but if you've sent through that, you will accept JSON and that's kind of the priority.
Jess Archer:
The thing that's first is like the priority. If you're saying, except application slash trace on Laravel guys, this response wants JSON and that's the wording it uses. The request object in Laravel has a method that says it wants JSON, which you can use yourself and it's very powerful, but the exception handler says, does this response once JSON I'll give them a JSON version of the exception.
Jess Archer:
Again, if you've got debug on, it'll have more fields, like it'll have the exception and the stock price in JSON form instead of HTML form but yeah, except it's a really cool header. Some APIs don't work properly if you don't send it. So you might, if you've used postman with some APIs, sometimes you have to add except application JSON. Otherwise you'll only get HTML.
Jess Archer:
Laravel tends to be a little bit cleverer and tend to find, I don't always need to specify it. Content type is sometimes less useful. It's often in the return to say that what I'm returning is JSON but one little trick that I've really enjoyed doing lately is if I've got a resource that I can represent in multiple formats. Maybe I can represent that in HTML, JSON and PDF, you could create separate URLs for all of that, but to make them restful, require some naming gymnastics that I'm generally not too comfortable with.
Jess Archer:
I tend to prefer to use the except header to say that it's the one URL invoices slash 123 and I can say, I want the HTML version so I can send the except header to say, except HTML and in my controller or in my response, wherever I want to put it, I can use the request, help to say it does this one HTML, does it want JSON, does it want PDF. Once PDF doesn't exist in Laravel it's about using macros, you can create a once PDF.
Jess Archer:
You can have your code to be super expressive to say if request wants PDF and then you can do whatever you need to do to return the PDF version of that and set the content type of a response to be application slash PDF so that the browser kind of knows what it's dealing with and can, depending on how you're using it, even render it for you. Except in content types, super important, they're always there doing things, but you don't have to interact with normally, but you can and when you can, you unlock lots of cool power.
Matt Stauffer:
Yeah. It's another one of those things where sometimes we're getting the freedom, we're getting it for free without realizing like the whole thing you mentioned with Claire bells sniffing it but also sometimes when we use it, we get other things for free that we didn't expect because some other things are reading.
Matt Stauffer:
Some other packages you're using on the front of the backend are potentially reading or sending those headers and so if you know, to use them and read them, you might actually unlock, like you said, a whole bunch more potential interactions with the other packages and services and everything you're using.
Jess Archer:
Exactly. And there's no magic with it. If you specify that you want JSON, there's nothing magic that's going out automatically format. This Laravel is intercepting that and saying, okay, I'm going to return to JSON version of this. It's doing it for you, but it's still ... It's nothing in the spec that's saying it has to do it in this certain way it is implemented but you don't have to have to deal with it.
Matt Stauffer:
Moment of shame for me, sometimes I'm feeling lazy and I don't do that and instead what I do, and I actually did this on a project just last week is I just say, trying to remember what project I did in, and I don't know if it's open source or not, but I did just, there's like the end point, then there's end point dot. Like I literally did dot JSON.
Matt Stauffer:
That's not about option.
Jess Archer:
It's like an old school way of doing it, right?
Jess Archer:
It's an old school of doing it. Yeah. It feels like it's like a file extension, right?
Matt Stauffer:
Yeah. Exactly.
Jess Archer:
It's like the invoices dot HTML, invoices dot PDF or whatever.
Matt Stauffer:
Yeah. I literally built an API controller for it and there was the API controller that serves the dot JSON end point and there's the non API control that serves the HTML end point and in this particular application, there's a reason why I made it to controllers rather than serving with the same end point but I just mapped those routes differently.
Matt Stauffer:
I was just like, yeah. Things dot JSON goes here, things goes here and cool and I was like, cause I haven't done that since I think like rails maybe, and rails definitely did that for a bit and Adam was the one who showed me that they did it so robustly, but I was just like, "This is kind of nice." It's very transparent. It's very obvious what I'm doing here. Nobody's ever going to miss it and it was just so fast to program but I do think that headers are fantastic. I do think they're a really great way to do it.
Jess Archer:
The other thing to remember is headers are hard to send if you're just using your web browser, you can't put headers when you're typing in the URL in a browser whereas with that approach, you can, so if you need to direct a user like in the web browser to that URL, rather than JavaScript doing it, cause JavaScript, you can send whatever headers you want but if it's just a URL, someone clicks on it and it goes there. You can't control the headers of that.
Jess Archer:
Your browser will always send, I accept anything. So in those cases, a dot whatever is actually probably the best way to do it.
Matt Stauffer:
Yeah. And which in dot JSON is unlikely to be something where you redirect to the user too, but dot PDF could be.
Jess Archer:
Exactly. Yeah. I think it's perfectly acceptable. There's so many ways of doing it and if the HTTP spec allows or has something built in to do it, I will default to that but these aren't rules that you can't ever break, they're just guidelines that you should follow. Some of them you shouldn't break. There's certain headers that if you try and use them creatively, you can actually break things.
Jess Archer:
If you do get creative with certain headers, just know that. Certain proxies in cases might interpret those in certain ways and do certain things that you might not want.
Matt Stauffer:
Yeah. And that's why, like you keep saying conventions are convention so that we don't waste all of our time screwing around and sometimes all we've done is save ourselves time. Sometimes we've saved ourselves pain because when other people are following those conventions and we don't follow them, then we run into trouble.
Jess Archer:
Yeah. I think the worst example I ever did was when I wanted to return a base 64 encoded version of a PDF, I tried to get tricky with the ... I think it was the encoding header to specify that it was base 64 encoded. Cause I'm like, "Well, that sounds like it's right," but the way that I think, I don't know if it's proxies or brass is the way something interprets that heading was not what I intended.
Jess Archer:
I ended up ... There's when you've got a dot URL, you can say like application PDF and then comma, I think base 64 ended up using that as the mime type. I don't know how valid that is. Maybe I should just return that the content type is a string protect play I think it's the one I don't know ...
Matt Stauffer:
Who knows. I like that and it's interesting because there's even, and we're not going to go here cause we're already an hour and a half in, but if someone were to want to nerd out, even within those content types, there's subtypes and vendors and stuff like that. So like JSON API has a subtype of the application JSON slash JSON thing, and you can say this, isn't just JSON, this is JSON, according to this particular vendor spec.
Matt Stauffer:
You can go very far down that road if you weren't trying to wrap up a podcast on time, but yeah. There's a lot of stuff you can go there.
Jess Archer:
Yeah, exactly and sometimes it has actual practical uses. Other times browsers are like, yeah, they kind of treat them all the same.
Matt Stauffer:
Yeah. For sure.
Jess Archer:
It really depends on replication because the consumer, isn't always a browser.
Matt Stauffer:
Yeah. I have found that when I'm using PHP to consume other APIs, I'm really grateful for headers and status codes more than when I'm using anything else. Because I think that in PHP, I'm not a browser. I don't have all those conveniences built in for how to think through it and so I'm like give me some more information. I'm really grateful when they have actually built in more robust returns and headers and all that kind of stuff.
Jess Archer:
There's nothing worse than an API that returns the 200 when there's been an error because you can't use like ... Axios will pass that to the success handler, Laravel is new HTTP client treat that as an error. That's not client error or server error or error. That's a success response so if you've got a pass a 200 and dig into it and go, Oh, this was actually a failure. That's not an API I want to work with.
Matt Stauffer:
Yeah. No, we are actually just about to sunset an integration we did with an API like that. That also ... it's so funny cause we made fun of it so much because one of the things that also made us do was write Microsoft SQL in the URL, and we were always just kind of like laughing and then that's sort of like what graph QL is a little bit, like it's not in the URL.
Matt Stauffer:
We always made fun of it. We're like, "Yeah, they're literally having us pass them SQL queries," and I'm kind of like, "Oh, that's kind of the hot new thing now." We probably shouldn't have made it so much, but they also in code their errors is like 200 and stuff like that. They make other mistakes.
Jess Archer:
Okay. SQL rejection is the first thing that comes to mind when I hear SQL.
Matt Stauffer:
It's not very safe. We are pretty late in this, obviously this one's not following the normal structure of the podcast and that's fine. We talked about this ahead of time that we wouldn't, but I do want to ask the quick question of common challenges and gotchas. If I am just getting started with building restful APIs in Laravel on day one, are there any things that you want to make sure that I don't get stuck on or thing you see people tend to have trouble with?
Jess Archer:
No, I think I've probably covered them, making sure that the authenticated user actually has access to return the thing, especially if you're refactoring from [inaudible]. There's little things I find that I like to TDD or test driven development. My KPIs.
Matt Stauffer:
I was just going to say that. Yeah, totally.
Jess Archer:
I tend to do another Adam motherland term, which is programming by wishful thinking. I don't know if he invented it, but I heard it from him where I will write in my test. I'll actually write the API response. I want my server to return because that's how I experiment how it feels to use it because I can write the URL. I can write the payload and go, is this going to be nice to work with? And then the test helps me.
Jess Archer:
I run the test. It fails of course and then it's like, "Okay, now you need to go create the routes and the controllers and do this transformation and whatever else to get that shape of data." I can test on my sad path really easily. It's much harder to test some of those like in real life to simulate them. I test drive everything.
Jess Archer:
A lot of people like to use tools like postman and insomnia and HTT PI to do their API requests, like to integrate, to interact with the API. I tend to find I just use TDD in Laravel because that way, it's always there, it's part of the code base. I know with postman, you can save these things and run them, but I just want to do my code in PHP.
Matt Stauffer:
It takes a while to set it up in postman, right? Like you get your configuration, right. You get your headers, right. All that kind of stuff you tested, it looks the way you want and you can't save them but do that exact same amount of work to build the request and look at the response in your test and now you've got a test, right? That's going to stick around forever.
Jess Archer:
The postman one is making an actual HTTP request as a third party. Whereas the TDD is kind of simulating requests so there are subtle differences, but from a practical point of view, I don't think I've ever been bitten by that.
Matt Stauffer:
One other thing to think about as we talk about writing test is that a test is a really great place to remember, to catch all those access and authorization errors. If you just try to beat it in your brain, I'm going to test my APIs. And one of the things I'm always going to test is to make sure that I can't access somebody else's thing.
Matt Stauffer:
I can't delete somebody else's thing. I can't see somebody else's thing in the list, just get out. That's something you just need to do, and that will help you fast. Yeah, exactly. Get those as your first thing. They're all going to be red and then that's going to be a trail for you to follow, to figure out how to adjust your authorization and your scopes and everything like that. So that's not a list anymore.
Jess Archer:
Exactly. Yeah. A hundred percent agree with that.
Matt Stauffer:
Okay. So is there anything else you'd like to talk about on this topic?
Jess Archer:
I feel like I had something, but then I've forgotten that so too bad, I guess.
Matt Stauffer:
Well, you know what, if you message me later, I'll throw the show notes. Otherwise everyone should just follow you on Twitter anyway, Jess Archer codes and we'll talk about other plugs in a second and then I'm sure you'll tweet it out there. If someone wanted to learn more about building APIs, whether in Laravel or in general, or even the higher level concepts of APIs, as you described them earlier, not just web APIs, where would you turn them to learn?
Jess Archer:
It's pretty a pretty broad topic as we've sort of discussed. I mean, you can kind of look at the Wikipedia definitions, but those are always tend to be pretty technical when you get to computer science sort of things, LaraCon obviously it's going to be one of the best places to learn anything. Adam widen has a lot of great courses and even just free material talks, there's been so many LaraCon talks.
Jess Archer:
You had that amazing Laravel JSON API talk at LaraCon. I was so excited when you did that and I thought the topic was I'm like, "Yes, I can't wait to see this one," because it's something that I've struggled with as well. I don't want to go deep on it, but like trying to implement JSON API truly in Laravel is not as easy as you would like it to be.
Jess Archer:
In terms of like the nested resources, Adam Allan has a ... it was a talk called credit by design. I think that really explains the most elegant way to do restful in my mind, entered in nasty things and had a stick to the five restful methods. So I would encourage everyone to watch Credit by Design. It's something I share all the time with, with people. So yeah. Yeah.
Matt Stauffer:
Anything Adam does, somehow, even if it's not about this tends to leak out like teachings about this, even Adam's testing course, you're going to learn a lot about it, about the and HTTP
Jess Archer:
Even the talk he did, the test driven Laravel talk that inspired the course. They all kind of go through a lot of those sort of same ways of thinking.
Matt Stauffer:
One of the things I learned most from Adam, I think I talked about this in the testing episode with him is that you can do robust testing of user interactions when instead of testing, they clicked the form and did the thing, you test the HTTP response and then the result you get back. And that's true, not even just in APIs. Right?
Matt Stauffer:
A lot of this stuff we're talking about in terms of testing APIs is really true about testing all calls in which lines up again with what you're saying at the beginning, which is that an API is not just a web API. It is just two things interfacing with each other, two computers talking to each other. So it all comes around.
Jess Archer:
The other thing Actually, I did want to say just on testing real quick is that often times when you're writing an API, the consumer of the API isn't in that code base and your full test suite can actually involve that software. In that case, for me, my tests are actually representing the consumer of the API and so they try and make them treat it as a black box for the most part of say the setup, you know, I sometimes need to see things, but for the most part, if something is going to break in a way that the front end, for example will break, if it's in a separate repository, I want the test to be there, to catch that first because it's almost like the bodyguard for the front end to say, "Hey, now you've changed that," and the front end is not expecting that
Matt Stauffer:
This is the contract we promised and I'm going to make sure you continue fulfilling it.
Jess Archer:
There are other things you can do with like API blueprint and swagger and all these things that can help you define contracts and adhere to them but I still find that a test at the end of the day is often just the simplest thing for most applications.
Matt Stauffer:
Yeah, I agree. Okay. So if personal fund moment before we give a plug, so you, at the beginning of your talk at lyric on AAU, I'm actually going to hold and it's also on your website. So I'm going to go pull it up on your website so I can read it correctly. There's a particular phrase that you used exactly on your website and exactly in your letter, kind of you talk where you said I've worked on some pretty interesting projects, including a chemical warehouse management system, a POS system.
Matt Stauffer:
It was an exact the same. A telephone robot, a crypto trading robot, even software for the place and you talked about finance and the letter contact. I feel like there's a lot of interesting things there. I kind of would assume that like, well, chemical warehouse has chemicals, but it's probably, actually not as interesting as it seems, just because in the end, it's just like any other warehouse point of sale system.
Matt Stauffer:
We have these crypto trading robot. I feel like one of these has got to be the wildest and most interesting, and I would assume probably crypto trading robot, but I'm not going to make the reception of those. I know. What can you tell us one really interesting story or thing you learned or something like that out of one of these wildly? Interesting.
Jess Archer:
Okay. So real quick on the chemical warehouse thing, it's not the interesting one, but it was designed to run on a laptop, like one of those Panasonic Toughbooks that sat in a forklift and yeah, it would give them the layout. It was like, it was basically for them to catalog where the chemicals were and then they moved mix them and create new chemicals, all that sort of stuff. That was really fun. Cool. Very long time ago, pre Laravel.
Jess Archer:
The crypto trading robot is not actually that exciting. I mean, crypto exchanges all have APIs. It was kind of designed around this idea of arbitrary where you can find the same thing for two prices at one place and if it's a big enough difference, you can buy it in one place, transfer it and sell it and it would like spy for all those things.
Jess Archer:
That was pretty cool. The post system is pretty boring. Let's touch screen though. So like, you know, just a bit of JavaScript of the touchscreen and it had like when you print, it opened the cash drawer. So I had a receipt printer triggered from a web browser and the stuff I have for the police is really interesting. Helping police send referrals for people in need that was needed to be very sensitively handled.
Jess Archer:
It was a lot of victims of domestic violence getting referrals. So making sure referrals never got lost all these like multiple redundancies, super critical.
Matt Stauffer:
Web based as well. They would use it on their laptops.
Jess Archer:
Laptops and iPads, but the telephone robot is probably my favorite one.
Matt Stauffer:
Okay. Tell us about it.
Jess Archer:
I was contacted by Australian marriage equality a long time ago, who were getting, they had got a bunch of money from Ben and Jerry's to do this campaign called quality calling and basically it was set up where people would ring phone number. They would enter their post code so that it could determine who their local politicians were. And then they would record a voicemail, a message of support for marriage equality. Yeah. And so then this robot would, so it was a phone robot where it was going to press one, do all this sort of stuff.
Jess Archer:
We had a celebrity here record the, all the voice recordings and it was all done with like, I think it's like, Twilio is.
Matt Stauffer:
Yeah. I was going to ask you. It was two and a half.
Jess Archer:
And so then every morning it would ring these politicians office.
Matt Stauffer:
And just play back the recordings.
Jess Archer:
Yeah. It was like an answer machine. It's like you have five messages of support for marriage equality, press one, to hear that. And we had things in NASA, they could opt out of it so that ... cause we had some hateful politicians, but it had all systems of like press one to recall back in 10 minutes or press one to snooze until tomorrow and like all these different options.
Jess Archer:
And so this little code paths had got to do and just recording them if the person consented to their message being tweeted, it would upload at SoundCloud and then tweet automatically link to that recording online and if, when they were doing the recording, it's like press whatever to, if you would like to share your recording publicly.
Jess Archer:
It was so much fun to work on and it was just crazy having this little robot that people were bringing up at the start of each day it would just ring the opposite.
Matt Stauffer:
That's really cool. Yeah. We recently had a project that was a public good project and it's in Chicago and my business partner, Dan was like, "It's very weird to be hearing radio advertisements every day for this thing we worked on," because it's like, I imagine you had that so much experience. Where you're like, everybody you know is seeing the advertisements for this little tool that you built. Right. And it's like, Oh, that's so cool.
Jess Archer:
Have you heard of Jimmy Bonds? The singer, he's a famous Australian singer. He promoted this thing like on TV and stuff.
Matt Stauffer:
Oh, cool. And you're like, "I did that."
Jess Archer:
That was like Laravel 4.3 maybe.
Matt Stauffer:
Oh, it was my Laravel. Very cool.
Jess Archer:
Yeah. It's my first project I ever did because it was when I was doing as a side project, the place I was working at the time was all WordPress and I'm like, I want to play with Laravel. I've heard so much about it and I was given an excuse to play with it.
Matt Stauffer:
I like it. I was almost going to ask you about music motorcycles, but I had to ask about these ones instead cause I've just, I was so interested in that. Okay, cool. What can we plug people should follow you on Twitter. What else? Jess Archer codes right?
Jess Archer:
Jess Archer codes on Twitter. My website is jessarcher.com. I don't have any products really. I mean, I've got gifty duck. If you want to go and see an example of how I build an SPA with an API behind it, you can go to giftyduck.com and register for that completely free but I don't really have ...
Matt Stauffer:
Basically podcasts?
Jess Archer:
Oh, basically podcasts Yeah. Definitely check out basically podcasts. Jay Mac and I, we kind of do little mini series on different topics that are on testing and streamlining code and Laravel. We do six episodes at a time, then take a break. Two LaraCon talks under my belt now, which I still can't believe I've done.
Matt Stauffer:
Yeah. And you killed it. You're a great speaker. You present as a conference speaker, you present that same way I was telling you earlier where you feel like you're a college professor, but not in like a boring way. You explain these things very robustly and I feel a little intimidated because I feel like I'm like a college student.
Matt Stauffer:
When I give talks I'm like, and then that was really fun whereas you're like very composed. Anyway, go check out Jess's talks, go check out her podcast, go follow her on Twitter. Cause she's great. I did not know that you would only join Twitter after LaraCon, you the first year that blew my mind.
Matt Stauffer:
In my mind, you kind of like did a little bit come out of nowhere, but I also figured, even though you came out of nowhere a lit bit, you'd also been around for ages. Obviously you've been programming for a long time, but yeah.
Jess Archer:
Yeah. Since, I don't know about 15 years now. I think it's fun but only after I went to LaraCon a year, I was really excited to like there's a LaraCon conference and I was really passionate about Laravel and that's when I discovered that there was a community on Twitter and I joined and it's just only brought good things to me so far.
Matt Stauffer:
I love it. Well, Jess, thank you so much. This was freaking brilliant. This was so much fun.
Jess Archer:
Thank you for having me.
Matt Stauffer:
It's obvious that you have way more to teach. Again, I hope that we get to learn more from you on these topics, but this has been just really, really helpful. I learned a lot and everybody else learned a lot, so thank you.
Jess Archer:
Thank you.
Matt Stauffer:
Everybody. We'll see you all next time.
Jess Archer:
See you.
Creators and Guests
