Introduction to the Directus API & Documentation
Hi, Bryant here for Directus. Welcome to another lesson in the onboarding series. Today is all about using the Directus APIs.
Every single thing that you can do inside the Data Studio, you can do also via the API. And there are some other things that even you cannot do inside the Data Studio that you can through the API. So let's dive into looking at the APIs.
The first thing that I want to call to your attention is just our documentation. So go to docs.directus.io and our API reference is over here in the left. It has a wealth of information on how to interact with the API. Pay close attention to the filter rules. If you're using the SDK to connect your front end, we've got that in a different video, make sure you pay attention to that. But each different collection inside Directus is broken down into the items here and you can really learn a lot on how to work with the API.
Making Your First API Request in Postman
So for me, let's pull up our Directus project. Hey, that's great. I'm going to go in and just grab our URL and let's fire up Postman. Not my favorite tool, but it will do the job. And we'll create a new, let's do a new collection. We'll call this Directus. I'll zoom in a little bit more so you guys can see. Let me move some of this stuff out of the way. Oh, where did it go? It completely disappeared. Yeah, that's fine. How do we hide it? Okay.
All right, so let's start with a new request inside this particular collection. And I'm just going to use this. All right, so this is our base URL. To access our content we're going to use /items/ the name of the collection. So I'm going to do posts in this case. We'll see what we get back. We're getting some data back. That's great. This is our first jumping off point.
Understanding Roles, Permissions, and API Access
Let's talk about roles and permissions. So the reason why I am able to get this data is because inside our roles and permissions, inside our project, the public role has a lot of read permissions. Specifically for our blog post collection, it allows any item with the status published to be viewed by the public. But if I were to disable this, let's just do no access to reading the blog posts, and we go back and do another test here inside Postman, we will get an error. This is, "Hey, you can't access this. Never gonna get it."
So what we could do here, now let's talk about authentication.
API Authentication Methods & JWT Login
There are two ways to authenticate. The public role obviously controls what the API has access to without authentication. The two ways to authenticate, if we go into the docs, we go to our authentication section—my kids have got to me today—we can use temporary tokens, JWTs that are generated by the login endpoint or mutation if you are using GraphQL. Or we can use static tokens. Static tokens never expire. They're great for server-to-server communication, but obviously you need to be very careful about who you share those tokens with. Make sure you obscure them. So let's try both out and see what happens.
We're going to go in and let's try the auth endpoint with just an email and password. So we'll go inside Directus. I'm going to save this one, save this request. Let's call it Get Posts just so I've got access to it. We'll put it in that Directus collection. Cool.
All right, so we will, let's just duplicate this tab and now we're going to do auth/login. And the params that we're going to pass in the request body—so this is going to be a POST request—are going to be email and password. Email. All right, that's going to be test user example. And I've got the most secure password of password.
Okay, so we can see there that we get our access token and we get a refresh token that we can call to refresh the access token. And that's what we would use to store our authentication and log in.
Now I can also do this via... Postman does not store this automatically. Trying to understand how you could save that in Postman to do testing, but beyond my grasp, so apologies there. But the other way to authenticate is using our static tokens.
Authenticating with a Static Token
So the static tokens, you would just pass in either a query parameter or the authorization header. So we'll go into our application, let's generate a static token. Let's just use the admin user for now. That'll be good. All right, so we'll save this static token. Copy, paste. Open back up to Postman. And let's close out that request. We're going to go to our authorization. I think there's somewhere you could set this for the entire collection. We'll go to Bearer Token and pass that token in, save it. Now we get our data back. Excellent.
Querying Relational Data with the 'fields' Parameter
So that is how authentication works. Let's talk about our actual queries that we're passing to the API. I'm going to zoom back out a little bit so I can see all of this. One of the things that you'll notice is we have a couple of different relationships here. By default, it is just passing back all the root level fields on my posts collection. So that's why I see an ID for author, category for, or an ID for the category, and other things like our SEO data as well, because those are separate collections that are part of a relationship.
Now how can I get this data in a single call? Hands down one of my favorite features of Directus. I will pass in a query param called fields and I'm just going to do this where I say get me all the root level fields, that's what the asterisk is for, and then I do a *.*, really fancy. And now we'll see that I have all the author data, I have the, where are you, category, all my category data, I've got my image data, I've got our SEO data. So I can use these wildcards or I can even just go in and say, okay, I want all of our root level fields, but I want the seo.title. And this thing is GraphQL-like in that I give it my fields that I want and I could save bandwidth, speed up our request by passing in only those particular fields that we need without having to use GraphQL.
Advanced Queries: Sorting & Aggregation
All right, so now let's dive in a little deeper. I'm just going to return the titles for now. And then maybe we want to sort those by alphabetical order. So here I could do sort and pass in title. So now we've got alphabetical or ascending order. If I want to do descending order, I just put a hyphen in front of that. And now we can see that we're sorting by descending order.
Cool. All right, what else do we have in the API? Again, we could be here all day if we look at the global parameters that are available. search does a full text search for any string and text field types. Very handy. It's far less optimized than the standard filter rules, but certainly handy, has its own uses. The filter rules are infinitely vast, infinitely deep. We can spend a whole 30 minutes talking about those, so I encourage you to check out our documentation. You know, we've got like pagination and everything that's already in here.
One of the cooler features is the ability to do aggregation and grouping right from the API. It is the same APIs that power our Insights feature actually. So I could go in and say, hey, we want to aggregate the count of how many blog posts that we have. So let's take a look at how we do this. I'm just going to go in, we'll do aggregate[count] and I'm going to pass in the ID and I can see I've got 16 blog posts currently in this particular instance.
Generating & Using the OpenAPI Specification
In an effort to keep this one shorter, I'm going to show you guys one or two more things. Let's just keep it to one, right? And then you can play with the APIs on your own, come back to us with questions that you have.
One of the other things that I do want to show you inside the server utilities is the ability to grab an OpenAPI spec that is specific to your Directus instance. So you have to be the admin user to get this data, but it is very nice because then I can come in and grab this OpenAPI spec. Let's save, how do I save this response? I'm just going to say api-spec, save that to my desktop. And then inside something like Postman, all I have to do is come in and do a, where's my new collection? Collections, we will import a collection. We'll just pick that file from our desktop. Boom, import that. Dynamic Imports API specification. It's thinking, it's thinking. Okay. And now we've got our API, we're set up to test inside Postman. So I could go in and within our Items collection, if I drop that down, we'll get a list of all the different collections that are inside our API or inside our project with the proper calls for each of those. And it shows you the exact params that you can pass, which is really, really nice.
So this is how you interact with the API. Don't forget to pull down that OpenAPI spec if that's helpful for you. And if you have questions, specific questions, those are easier to answer than a generalized API FAQ. Shoot them to us inside the community. Thanks, can't wait to see you on the next lesson.
