Feb 19, 2022 6 min read Using Directus

How to use the REST API on your website

REST APIs are a very powerful method for retrieving your data from Directus. In this article, I'll show you how you can query, create, update and delete records as well as some advanced techniques that will be useful when creating websites.

To use a REST API on your website you will first need an Authentication Token from Directus. Then you can use your favourite server-side scripting language to perform the queries.

But, how does this work?

The idea behind using an API with your website is to dynamically pull data from Directus and display it to the user. This can be page content, user information, products, images etc. The website essentially becomes a shell.

As and example, lets say the homepage is opened, you can have a query to fetch the website's main menu, then a query to find the homepage banner. Then several queries to fetch featured content. After each query is made, you will need to process the data into HTML. This can be from template library or coded into a page template.

Alternatively, you can use the javascript SDK from Directus.

For this article, I use a free application called Postman to test my API queries and visualise the responses. Let's dive into the first segment of most APIs - Authentication.

Authentication

Every API is different when it comes to Authentication but in Directus, all you need is a Bearer token. You can create once in Directus by using an API user with a token defined in the User Management portal. This token is used in the authentication header.

In Postman, create a new Collection and open the Authorization tab and paste your token into the Token field at the bottom.

For you application or website, you need to add the token to the authorization header. I'm writing these commands below in raw curl which can be easily translated into your chosen language.

curl -H "Authorization: Bearer your-bearer-token"

Query the API with REST API

The REST API relys on the URL to specify the query also known as GET. Here is an example from Directus.

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

With no parameters, this will return all columns for the data. We can limit the response be specifying what fields we would like to return. To do this, we need to add a paramenter to the URL.

https://directus.example.com/items/articles?fields=id,title,author.first_name

Notice the author has a child field called first_name seperated by a full stop (.). Usually, realtional content is shown as the ID, but if you specify columns from with in the relational table, you can include the data all in the one query.

In Postman, create a new Request and choose GET as the method. The URL is the endpoint mentioned above with the fields parameter. You will notice the Query Params table will automatically populate with the parameters from the URL.

Once you click Send, you will receive the same JSON response as the GraphQL query.

{
    data: [
        {
            "id": 1,
            "title": "Hello, world!",
            "author": {
                "first_name": "Robert"
            }
        }
    ]
}

The query in CURL is quite simple:

curl -H "Authorization: Bearer your-bearer-token" https://directus.example.com/items/articles?fields=id,title,author.first_name

But how do I query a specific record?

To query a specific record, we can reuse the URL from our previous query then add the ID after articles. I've added /15 before any parameters.

https://directus.example.com/items/articles/15?fields=id,title,author.first_name

The JSON response is slightly different, where the data value is no longer a list but a single item.

{
    data: {
        "id": 15,
        "title": "More Information about this",
        "author": {
            "first_name": "Sarah"
        }
    }
}

Again, the CURL is quite simple:

curl -H "Authorization: Bearer your-bearer-token" https://directus.example.com/items/articles/15?fields=id,title,author.first_name

Creating a New Record in REST API

To create records using the REST API, you use a URL like the one below but without any parameters. Note, the URL does not have a trailing slash.

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

Next, we need to POST some data to this URL. It's very important to supply all required fields and honor any field restrictions, such as INT, DATE, BOOLEAN.

In Postman, form data can be posted using either form-data or x-www-form-urlencoded options in the Body tab.

The response contains the full scope of the record.

{
    data: {
        "id": 16,
        "status": "published",
        "date_created": "2022-02-05T13:00:00.000Z",
        "date_modified": null,
        "user_created": "bb6b83ed-aad3-4d6f-be43-1361cd9162cc",
        "user_modified": null,
        "title": "Hello world!",
        "body": "This is my first article",
        "author": 1
    }
}

In CURL, this request looks like this:

curl -H "Authorization: Bearer your-bearer-token" -X POST -F 'title=Hello world!' -F 'body=This is our first article' https://directus.example.com/items/articles

Or if you would prefer x-www-form-urlencoded:

curl -H "Authorization: Bearer your-bearer-token" -X POST -d 'title=Hello world!' -d 'body=This is our first article' https://directus.example.com/items/articles

I've noticed that booleans need to be a string "true" or "false" and not ture or false.

Update a Record in REST API

REST API update has a few differences to the creation request. The method needs to be changed to PATCH and the ID needs to be added to the URL:

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

The biggest change is the JSON input requirement rather than form-data. In Postman, choose the PATCH method and fill in the required fields.

Observation: Boolean fields cause an error. Make sure to convert true and false to a string.

The CURL request is different as well.

curl -H "Authorization: Bearer your-bearer-token" -H "Content-type: application/json" -X PATCH -d '{"title": "Hello world!"}' https://directus.example.com/items/articles/16

Delete a Record in REST API

REST API delete quite simple. The method needs to be changed to DELETE and the ID needs to be in the URL:

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

The CURL looks like this:

curl -H "Authorization: Bearer your-bearer-token" -X DELETE https://directus.example.com/items/articles/16

Advanced REST API Usage

Added extra parameters works quite differently for REST APIs, the main difference is the filter paramenter which uses square brackets [ ] for each dimension of the filter array.

To replicate the same example as above, here is the request URL. Note the format of the filter parameter.

https://directus.example.com/items/articles?fields=id,title,author.first_name&filter[author][first_name][_eq]=Robert&sort=-date_created&limit=100&page=2

Observation: If you have any spaces in your filter values, make sure they are replaced by a +, also know as url encoded.

Again, what we expect to see is 101 - 200 of articles authored by Robert in descending order of when they where created.

The query in CURL is quite simple since all the parameters are in the URL.

curl -H "Authorization: Bearer your-bearer-token" https://directus.example.com/items/articles?fields=id,title,author.first_name&filter[author][first_name][_eq]=Robert&sort=-date_created&limit=100&page=2

Conclusion

You now have the essential tools to get started with the Directus REST API. Postman is a great application for testing the API and understanding the response. You can output your data on your website by creating templates and outputing the values into your templates.