How to use Postman with Directus
Postman is an essential tool in any project. You can connect to any API then test out the various endpoints and responses. In this article, I'll cover how to connect Postman to Directus.
First, obtain your Static API token from Directus and set up the Bearer Token in Postman's Authentication, then familiarise yourself with the API documentation. Lastly, add some endpoints and test the queries.
Step 1: Directus API Token
Login to Directus and open the User Management module. If you haven't created an API user, create a new user now. At the bottom of the API user, there is a field labelled Token. By default this is always blank. If empty, type a token now and save the user. There are some great token generators on Google. Copy the token from the field.
Step 2: Permissions
Permissions are a very important part of APIs. It keeps you data safe from accidental or deliberate changes that cause havoc on your system. It's very tempting to use the Administrator privilages, but it's definately worth having a dedicated API Role.
Create a new role in Directus and assign it to the API user. On the role, you'll see a list of all the collections in Directus and the permissions for Create, View, Edit, Delete and Share. Simply grant access to the required actions for each collection. Bare in mind, relational tables need to be visible to return the data and editable to write relational data.
Step 3: Create a Postman Collection
In Postman it's important to create a collection for each service. In this cas you can call it Directus, or something relative to the project. To create a new collection, click the + (plus) symbol next to the Collection menu button then name your collection.
Next, change the Authorization type to Bearer Token.
A Token field will appear. Paste the token from the Directus API and click Save. If the save button is not showing you need to close the right-side panel.
You can add as many collections as you need and you can add multiple Directus projects with ease.
Step 4: Create API Requests
Now that you have a collection, you can create some requests. Right click on the collection in you left navigation or click the ellipsis menu icon when you hover the mouse on the collection. Choose Add Request.
Give the Request a meaningful name then add the URL for the Directus API. If you're using REST API, the URL will look like this where directus.example.com is your domain name for Directus and articles is your collection in Directus.
If you want to use GraphQL, the URL is always the same.
It's worth familiarising youself with the API Documentation.
Types of Requests
When making a request to the API, you can choose a Method.
Request is sent in the URL and any parameters included after the URL using a question mark (?) and separated by ampersand (&)
This is used by GraphQL for most requests but also by the REST API to create new records. Parameters are included in the body as a form input or JSON.
Very similar to post but this updates content in Directus. Parameters are included in the body as JSON. Note: Form is not supported.
As the method suggests, this deletes content in Directus.
A relatively new method, this one allows you to query the collection.
If you are debating whether to use GraphQL or REST API, I have an article that covers how they compare in Directus.
Step 5: Run the Request
Next to the URL is a big blue button labelled Send. Click this to run the request.
The response is displayed in the bottom half. Normally we'd expect to see a JSON output but HTML is supported too.
Here is an example of a valid response.
Here are some common problems and how to resolve them.
You don't have permission to access this
This is becuase your API user does not have permission to access the collection. You'll need to update the Role and grant View permission to this collection.
This occurs when there is a mistake in the request. Check each part of the request including the parameters and values. A common cause is the Boolean field type, the value must be in quotes ("true" or "false").
Postman is a powerful tool to explore APIs and is not limited to Directus. You can include any API service conveniently in one place, include multiple Directus projects. If you keen to learn more about Directus, be sure to look at my other articles and subscribe to be sent future articles when they become available.