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.

Everything you need to know about Directus Roles

Roles are a core feature of Directus which controls how your users interact with the data. Learn how you can use roles to build a successful team and secure your application.

Learn DirectusTim Butterfield

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.

https://directus.example.com/items/articles

If you want to use GraphQL, the URL is always the same.

https://directus.example.com/graphql

It's worth familiarising youself with the API Documentation.

API Reference | Directus Docs

Directus 9. An Instant App & API for your SQL Database.

Directus Docs

Types of Requests

When making a request to the API, you can choose a Method.

If you are debating whether to use GraphQL or REST API, I have an article that covers how they compare in Directus.

GraphQL vs REST API in Directus 9 Headless CMS

Directus 9 supports both GraphQL and REST API, which one should I use? This article will cover the usage of both so you can decide which one suits you.

Learn DirectusTim Butterfield

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.

Troubleshooting

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.

Bad Request

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").

Conclusion

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.