[00:00]
Hello guys, how to create APIs in
[00:02]
Laravel. There's no specific
[00:04]
documentation section for that. There's
[00:06]
no specific starter kit in Laravel. So I
[00:09]
decided to give an overview in this
[00:11]
video in roughly 14 minutes or so to
[00:14]
help you get started with fundamentals
[00:16]
of APIs. This will be a shortened
[00:19]
version of the fundamentals of my new
[00:21]
updated course on Laravel API from
[00:24]
scratch. So I reshot the videos, the
[00:26]
video version. So all the lessons are
[00:28]
video plus text. So the whole course is
[00:31]
1 and a half hours plus some text
[00:33]
lessons. But in this video I will try to
[00:35]
summarize the main things that you need
[00:37]
to know in 14 minutes. But if you want
[00:40]
the full course the link will be in the
[00:41]
description below. Let's dive into
[00:43]
creating APIs. The first thing you need
[00:45]
to know is when you install the Laravel
[00:47]
project, there's no API by default. So
[00:50]
if you run Laravel new, none of the
[00:52]
starter kits are for API projects. So
[00:55]
you choose none and then you install API
[00:58]
separately. Enable that functionality
[01:00]
because it's not enabled by default
[01:02]
since Laravel 11. So after that
[01:05]
installation, if we go to the source
[01:06]
code, there's no routes API file.
[01:09]
There's only routes web. So you need to
[01:11]
enable the API. By default, Laravel
[01:14]
assumes that you don't have API and you
[01:16]
don't work with API. So you need to run
[01:18]
PHP artisan install API which will do
[01:22]
two things. install Laravel Sanctum
[01:24]
which we will later use for
[01:25]
authentication including the migration
[01:27]
for the tokens but also what is more
[01:30]
important I'm sure if you noticed on the
[01:32]
left now we have routes API file and the
[01:35]
final thing to do with that installation
[01:36]
is add Laravel Sanctum has API tokens to
[01:39]
user model again for later
[01:42]
authentication but in the routes now we
[01:44]
have routes API where exactly we will
[01:46]
put our routes for this video but to
[01:49]
finish the installation in the user
[01:51]
model let's have has API tokens which is
[01:54]
autocompleted by my cursor like this.
[01:57]
Next I will show you how to get the data
[01:59]
via API. So this is the database table
[02:01]
of categories and we will create a route
[02:04]
and a controller to get that with the
[02:06]
API call. So we make the controller I
[02:08]
specifically specify namespace from the
[02:10]
very beginning and then in the routes
[02:12]
API we do route get categories
[02:14]
controller with index and controller is
[02:17]
used on top but in fact it's not correct
[02:20]
autocomplete. It's this. Now in that
[02:22]
category controller in the index method
[02:25]
all you can do is just return eloquent
[02:27]
collection and then Laravel will take
[02:29]
care of returning that as JSON. So in
[02:32]
your API client like Postman for
[02:34]
example, you can just launch the URL
[02:36]
which is powered by my Laravel herd the
[02:38]
API is the default prefix of all URLs in
[02:42]
routes API file and you just launch get
[02:44]
request and get the list of categories
[02:47]
with all the columns as they are from
[02:49]
the database. But in real projects you
[02:51]
probably want to customize the columns
[02:53]
that are returned. For example, return
[02:55]
just ID and name and not the timestamps.
[02:58]
For that usually in Laravel people use
[03:01]
so-called eloquent API resources. So we
[03:04]
run artisan command make resource with
[03:06]
model name resource and then it
[03:08]
generates the file category resource
[03:12]
which should return the array by default
[03:14]
parent to array but this is where we
[03:16]
override the defaults and return what we
[03:18]
want to return from that category model.
[03:21]
So for example, we want to return this
[03:23]
ID, then this name and timestamps. And
[03:27]
in this case, we don't want to return
[03:29]
the timestamps at all. So let's leave it
[03:31]
like this. And then in the controller to
[03:33]
enable that eloquent resource, we wrap
[03:36]
our category all into collection, which
[03:40]
should be also added in the use section
[03:42]
on top like this. Now if we launch our
[03:45]
postman, the same URL, I don't change
[03:47]
anything. I just relaunch. We have this
[03:50]
changed in fact two changes. First we
[03:52]
return only what is specified in the API
[03:55]
resource but also we have a new wrapper
[03:59]
layer called data which is closer to
[04:02]
general API standards on the market
[04:04]
outside of Laravel because there may be
[04:07]
additional stuff in addition to data
[04:09]
like pagionation like other related
[04:12]
resources and stuff like that. But if
[04:14]
you want you may disable that in your
[04:17]
app service provider of Laravel project
[04:18]
in the boot method you may specify JSON
[04:21]
resource without wrapping like this. And
[04:25]
now if we relaunch the same request we
[04:28]
don't have that data but personally I
[04:30]
wouldn't advise that this is kind of a
[04:32]
standard and it's generally good to use
[04:34]
market standards for the future. And let
[04:37]
me show you that pagionation in action
[04:38]
that I mentioned. So all you need to do
[04:40]
to use pagionation from eloquent is
[04:42]
change all to for example pagionate by
[04:45]
default pagionate by 15 but we have only
[04:47]
three records in the database. So we'll
[04:48]
do pagionation by two records and that's
[04:51]
all we need to do again laravel will
[04:53]
take care of providing the structure and
[04:55]
the fields automatically and let's
[04:57]
relaunch that and see what happens.
[05:00]
First we have the same data but as you
[05:02]
can see two records only and then this
[05:05]
is the reason why the data separately is
[05:08]
useful. On top of data in addition to
[05:10]
data you have links to all the pages you
[05:13]
have meta data how many pages are in
[05:16]
total what are the links for pages the
[05:19]
link for next page and other settings
[05:21]
related to pagionation. Next, I will
[05:24]
show you the full crud of API based on
[05:26]
the categories. And I already prefilled
[05:28]
the code to save you some time. So to
[05:30]
show a specific category, you just
[05:32]
return the resource of that category.
[05:34]
And this is where category source is
[05:37]
useful because it's reusable. So when
[05:39]
you launch get with categories ID1, this
[05:42]
returns ID and name only. And this is
[05:45]
all powered by route resource or in fact
[05:48]
separate. There's route API resource
[05:51]
which covers five methods instead of
[05:54]
typical seven because APIs don't need
[05:57]
create form or edit form. So there's
[05:59]
only five methods index, show, store,
[06:02]
update, and destroy. So I showed you how
[06:04]
show works for store method. It's a
[06:07]
typical Laravel thing. So if you worked
[06:09]
with web Laravel, it's nothing really
[06:11]
different. The difference is what you
[06:13]
return. So you create the category, you
[06:15]
validate the category and then return
[06:17]
what if you use the same again eloquent
[06:20]
API resource with new model created or
[06:23]
updated model then again the structure
[06:25]
is similar. So if you do the post
[06:28]
request to add new category, you send
[06:30]
the body name as new category. For
[06:33]
example, we send and we get the data
[06:36]
again with ID and name using Eloquent
[06:38]
API resource. And by default for this
[06:41]
case for create Laravel returns 201 HTTP
[06:45]
status code instead of just 200 which is
[06:48]
in the same 200 success status codes.
[06:51]
And this is probably the most important
[06:53]
part of working with APIs in general
[06:55]
using correct HTTP status codes or at
[06:58]
least the first number of two which
[07:01]
means successful. And we'll return to
[07:03]
status codes in a minute. For now I want
[07:05]
to show the full CRUD. So this is what
[07:07]
happens when you create a new category.
[07:10]
Then for patch request or put it's
[07:12]
almost the same put or patch. Then you
[07:14]
do ID here and then you pass the name of
[07:18]
updated category for example. Then you
[07:21]
send and then it returns the updated
[07:23]
category but this time with 200. Okay.
[07:26]
And then finally destroy method. This is
[07:28]
kind of interesting. So what do you
[07:30]
return after there is no record in the
[07:32]
database. It's deleted. Typical thing
[07:35]
how developers return data here is
[07:37]
response no content which would return
[07:40]
status code 204. still two as the first
[07:43]
number which means success but no
[07:45]
content will be returned which is
[07:47]
probably a good indicator for the front-
[07:50]
end client that well there's nothing to
[07:52]
show. So if we delete the category
[07:54]
number three for example, we don't need
[07:56]
any body in this case. But if we even
[07:59]
pass that, it wouldn't be counted. We
[08:01]
send and as you can see no content here.
[08:04]
204 status code here. And if we try to
[08:08]
get that category by ID, we would get
[08:11]
404 not found. Which leads me to another
[08:14]
tip. If you get HTML as a result, it
[08:17]
means that you didn't pass important
[08:19]
header. So in the headers of your API
[08:22]
client whichever you use you do need to
[08:24]
pass accept application JSON then if you
[08:27]
get any error you get that error in JSON
[08:30]
which is friendly for API client in
[08:33]
JavaScript or whichever front end you
[08:36]
have. Next let's talk about validation
[08:38]
in Laravel and this is where we will get
[08:40]
back to HTTP status codes. So what
[08:42]
happens if we don't pass the name which
[08:44]
is required. So in the controller we
[08:47]
have request form request which has that
[08:49]
rule of validation. By default Laravel
[08:52]
in case of validation error will return
[08:54]
422 status code and will provide the
[08:57]
list of errors related to those fields
[09:01]
automatically forming the error messages
[09:04]
similarly how it would do on the web
[09:06]
just in JSON structure for the API. And
[09:08]
this is okay this is how it's supposed
[09:10]
to work. So your API client would see
[09:12]
422 status code and the first digit four
[09:15]
means that the error is on the client
[09:17]
side. So some data or some request
[09:20]
didn't go well. So they need to fix the
[09:22]
error on the front side like pass
[09:24]
different data or pass different
[09:26]
endpoint or something like that. But if
[09:28]
you don't do the validation on the
[09:29]
Laravel layer for example, let's remove
[09:32]
that validation rule which would lead to
[09:35]
SQL query being executed which will fail
[09:38]
because on the database level that
[09:40]
category name is required which then
[09:43]
will lead to if we send 500 internal
[09:46]
server error. And of course for
[09:48]
production APIs you would have appV
[09:50]
production so they will not see the SQL
[09:53]
error because otherwise it would be a
[09:54]
security issue. But generally when the
[09:57]
API client sees 500 error or five
[10:01]
whatever then means the error is on the
[10:04]
server side. So the front end would need
[10:06]
to report to you and you need to fix the
[10:09]
error. So it's your job as a backender
[10:11]
to do something like this. What I'm
[10:13]
saying here is that 400 and 500 status
[10:16]
codes are all errors but different in
[10:20]
what should happen after that error. And
[10:22]
the list of available HTTP status codes
[10:24]
is pretty huge. You can find them on
[10:26]
Wikipedia. So there's 200. Okay, we saw
[10:29]
that 200 created and others, but
[10:32]
probably you will use in your Laravel
[10:34]
projects only a few of them. So I found
[10:37]
this shorter list in Laravel docs for
[10:39]
HTTP client which works with external
[10:42]
API and these are the codes generally
[10:45]
accepted which have specific methods
[10:48]
which means that those are probably kind
[10:50]
of the most probable HTTP status codes
[10:52]
to happen. So you need to learn at least
[10:55]
those. What do they mean and in what
[10:57]
cases do they return these codes? But
[11:00]
the basics of HTTP status code is this.
[11:03]
I wrote an article on Laravel Daily.
[11:05]
This is for premium members. But I will
[11:07]
show you the point number one. The worst
[11:10]
practice of API is returning 200 status
[11:13]
code. If there is an error, you need to
[11:16]
always rely either on Laravel automatic
[11:18]
validation mechanism or specifically
[11:21]
return 4 to2 or 500 whatever is the
[11:25]
actual error. There's a classical meme
[11:27]
about it and I found the original on
[11:29]
Reddit here. So this is kind of the API
[11:31]
client happily receiving the message but
[11:34]
then inside of that message it says
[11:36]
error. Finally in this video I will talk
[11:38]
about Laravel Sanctum which is in itself
[11:40]
a huge topic. So I will just give an
[11:42]
overview from the doc. So you would
[11:44]
understand the concept because how you
[11:46]
use sanctum depends on what front end do
[11:48]
you use it from. And in the course I
[11:51]
have a separate big section with
[11:53]
potentially most popular front ends
[11:55]
Vue.js next and mobile flutter react
[11:59]
native with repositories how you would
[12:01]
use Laravel Sanctum for those. But in
[12:03]
this video as an overview so you would
[12:05]
understand the concept. If you use
[12:07]
Sanctum for API token authentication, it
[12:10]
probably means that you have front end
[12:12]
separate like JavaScript application
[12:14]
like Vue.js or any JavaScript which
[12:17]
calls Sanctum to get the API token. This
[12:20]
is where use has API tokens from user
[12:22]
model is useful and you have a specific
[12:26]
route to generate the token and return
[12:28]
it to the front end and then all the
[12:30]
requests from there from the front end
[12:33]
should contain that token for
[12:34]
authentication. And then in your routes
[12:36]
you use middleware o sanctum which would
[12:39]
check that token. Then the second way
[12:41]
how you would use Laravel Sanctum is for
[12:43]
so-called SPA single page applications
[12:46]
which don't use any token and instead
[12:48]
uses Laravel builtin cookie. So that is
[12:51]
a separate topic. You need to configure
[12:54]
domains. You need to configure
[12:56]
middlewares and then for authentication
[12:58]
you need to get so-called CSRF cookie
[13:00]
and then configure some more stuff. But
[13:02]
at the end in the routes, it's still
[13:04]
middleware of sanctum. Similarly how you
[13:07]
would use it in the first way. And then
[13:09]
the final way is for mobile application
[13:11]
authentication. It's almost the same as
[13:14]
the first way. You issue tokens, but in
[13:17]
this case you also have the request
[13:19]
device name for example to assign the
[13:22]
token to specific mobile device of the
[13:25]
client. And then that mobile device
[13:27]
should pass the token as bearer token
[13:30]
and authorization header. And on the
[13:32]
back end, same thing for protecting
[13:34]
routes. In all those cases, it's
[13:35]
middleware of sanctum to the route or to
[13:38]
the route group. So yeah, this is the
[13:40]
basic concept of how you use sanctum and
[13:42]
the basic concept of how you use API in
[13:44]
general. And this is where I will end
[13:46]
this video. So the goal of this video
[13:48]
was to get you started with the
[13:50]
fundamentals of API. So you can go and
[13:51]
create your APIs. You have enough
[13:53]
knowledge. But if you want to get deeper
[13:55]
and more practical again with Sanctum,
[13:58]
separate examples also talking about
[14:00]
uploading files and other features like
[14:03]
documentation, versioning, rate limits
[14:06]
and unit testing. I invite you to get
[14:08]
the full course available for Laravel
[14:10]
Daily Premium members as well as 80
[14:13]
other courses at the moment. The link to
[14:15]
that course will be in the description
[14:17]
below. But if you have any more
[14:18]
questions about APIs which I should
[14:20]
touch in separate videos here for free
[14:22]
on YouTube, let me know in the comments
[14:24]
and let's discuss. That's it for this
[14:26]
time and see you guys in other