How to use Postman with Directus

Postman is an essential tool in any project. You can connect the Directus API and test out the various endpoints and responses.

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.

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.

💡
Important: Whenever a new collection is created, you'll need to update the API role with the required permission. By default, access will be denied.

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.

Example of Bearer Token selection in menu

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.

Example of Token Field

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
Example of a query in Postman

It's worth familiarising youself with the API Documentation.

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

Types of Requests

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

GET

Request is sent in the URL and any parameters included after the URL using a question mark (?) and separated by ampersand (&)

POST

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.

PATCH

Very similar to post but this updates content in Directus. Parameters are included in the body as JSON. Note: Form is not supported.

DELETE

As the method suggests, this deletes content in Directus.

SEARCH

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.

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.

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.

Example of Items 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.

By continuing to use our website, you consent to use essential cookies. We also use optional tracking cookies which help us gather statistics to improve our services. Do you consent to these cookies?

I Consent Do not track