SDKs overview

Directus provides a core platform that exposes its functionality through a comprehensive REST and GraphQL API. To simplify interactions with these APIs, Directus offers official SDKs and benefits from community-driven libraries. These client-side tools abstract the complexities of HTTP requests, authentication flows, and data serialization, allowing developers to focus on application logic rather than raw API communication.

The primary official SDK is designed for JavaScript environments, encompassing browser-based applications and Node.js backend services. This SDK facilitates common operations such as reading, creating, updating, and deleting items, managing files, handling user authentication, and subscribing to real-time events. While the Directus API is accessible via any HTTP client, using an SDK can reduce development time and potential error rates by encapsulating best practices for API interaction.

Developers working with other programming languages, such as Python, PHP, or Go, often rely on standard HTTP client libraries or community-contributed wrappers to interact with the Directus API. The API adheres to common web standards, including JSON for data exchange, making it broadly compatible with various programming ecosystems.

Official SDKs by language

Directus currently maintains one official SDK, focusing on JavaScript environments. This SDK is designed to be versatile, supporting both front-end web applications and back-end Node.js services. It provides a consistent interface for interacting with the Directus API, regardless of the execution context.

JavaScript SDK

The official JavaScript SDK for Directus is named @directus/sdk. It offers a programmatic interface for interacting with all aspects of a Directus instance, including:

  • Data Operations: CRUD operations on collections and items.
  • Authentication: Handling user login, logout, and token management (e.g., static tokens, OAuth2, email/password).
  • Files & Assets: Uploading, downloading, and managing files stored in Directus.
  • Users & Roles: Managing user accounts and permissions.
  • Real-time Updates: Subscribing to changes in collections via WebSockets.
  • GraphQL & REST: Supports both API paradigms offered by Directus.

The SDK is actively maintained and kept in sync with the latest Directus core features and API changes, ensuring compatibility and access to new functionalities. The Directus SDK reference documentation provides detailed usage examples and API specifications.

Language Package Name Install Command Maturity
JavaScript / TypeScript @directus/sdk npm install @directus/sdk or yarn add @directus/sdk Official, Actively Maintained

Installation

Installing the official Directus JavaScript SDK is typically done using a package manager like npm or Yarn, which are standard tools in JavaScript development workflows. The installation process is straightforward and integrates into existing projects.

Prerequisites

  • Node.js and npm/Yarn installed on your development machine.
  • An existing Directus instance (self-hosted or Directus Cloud) to connect to.

Steps for Installation

  1. Open your project's terminal or command prompt.

  2. Navigate to your project directory.

  3. Run the installation command:

    If you are using npm:

    npm install @directus/sdk

    If you are using Yarn:

    yarn add @directus/sdk

  4. Once the command completes, the @directus/sdk package and its dependencies will be added to your project's node_modules directory, and an entry will be added to your package.json file.

After installation, the SDK can be imported into your JavaScript or TypeScript files and initialized to connect to your Directus instance. For detailed guidance on setting up your Directus instance, refer to the Directus installation guide.

Quickstart example

This quickstart example demonstrates how to initialize the Directus JavaScript SDK, authenticate with an access token, and fetch items from a collection. Replace placeholders like YOUR_DIRECTUS_URL, YOUR_ACCESS_TOKEN, and your_collection with your specific Directus instance details.

import { Directus } from '@directus/sdk';

// Initialize the Directus SDK with your API URL
const directus = new Directus('YOUR_DIRECTUS_URL');

async function fetchData() {
  try {
    // Authenticate using a static access token
    // For production, consider more secure methods like OAuth2 or email/password flow
    await directus.auth.static('YOUR_ACCESS_TOKEN');

    // Fetch items from a collection named 'articles'
    // Replace 'articles' with the name of your collection
    const articles = await directus.items('articles').readByQuery({
      fields: ['id', 'title', 'status', 'date_created'],
      sort: ['-date_created'],
      limit: 5,
    });

    console.log('Fetched Articles:', articles.data);

    // Example: Create a new item (requires appropriate permissions)
    // const newItem = await directus.items('articles').create({
    //   title: 'New Article from SDK',
    //   content: 'This article was created programmatically.',
    //   status: 'draft',
    // });
    // console.log('Created New Item:', newItem.data);

  } catch (error) {
    console.error('Error interacting with Directus:', error);
    if (error.response) {
      console.error('API Error Details:', error.response.data);
    }
  }
}

fetchData();

This example first imports the Directus class, then initializes an instance pointing to your Directus API endpoint. It then attempts to authenticate using a static access token. While convenient for quick tests or server-side applications with securely managed tokens, client-side applications typically use the email/password flow or OAuth2 for user authentication. Finally, it demonstrates fetching the five most recent articles from a collection, specifying the fields to retrieve and sorting by creation date. Error handling is included to catch potential issues during API calls.

For more advanced examples, including real-time subscriptions, file uploads, and user management, consult the Directus SDK Data Operations documentation.

Community libraries

While Directus provides an official JavaScript SDK, the open-source nature of the project has fostered a community that contributes libraries and integrations for other programming languages and frameworks. These community-driven efforts extend Directus's reach and provide developers with more options for integrating Directus into diverse technology stacks.

Community libraries typically emerge to address specific needs, such as:

  • Language-specific clients: Wrappers for languages like Python, PHP, Go, or Ruby, providing a more idiomatic way to interact with the Directus API than making raw HTTP requests.
  • Framework integrations: Plugins or modules for popular frameworks (e.g., Laravel, Symfony, Django, Rails) that simplify connecting to Directus and often provide ORM-like interfaces or authentication helpers.
  • Utility tools: Scripts or small libraries for tasks like data migration, schema synchronization, or custom command-line interfaces (CLIs).

The quality, maturity, and maintenance level of community libraries can vary. Developers should evaluate these projects based on their documentation, active development, community support, and alignment with their project requirements. Many community contributions are often shared and discussed on platforms like GitHub or the Directus Discord server.

Examples of community-driven efforts often include:

  • Python Clients: Various Python libraries exist that wrap the Directus REST API, allowing Python applications to manage content and data.
  • PHP Clients: Integrations for PHP frameworks to streamline data fetching and manipulation from Directus.
  • Go Clients: Libraries providing Go-specific structs and methods for interacting with the Directus API.

For the most up-to-date information on community contributions, it is recommended to explore the Directus GitHub organization and search for related repositories, or engage with the Directus community channels.