9.1 KiB
SDK JS
The JS SDK is a small wrapper around Axios that makes it a little easier to use the Directus API from a JavaScript powered project.
Installation
npm install @directus/sdk-js
Usage
import DirectusSDK from '@directus/sdk-js';
const directus = new DirectusSDK('https://api.example.com/');
NOTE All methods return promises. Make sure to await methods, for example:
import DirectusSDK from '@directus/sdk-js';
const directus = new DirectusSDK('https://api.example.com/');
async function getData() {
// Wait for login to be done...
await directus.auth.login({ email: 'admin@example.com', password: 'password' });
// ... before fetching items
return await directus.items('articles').read();
}
getData();
Reference
Global
Initialize
import DirectusSDK from '@directus/sdk-js';
const directus = new DirectusSDK('https://api.example.com/');
The SDK accepts a second optional options parameter:
import DirectusSDK from '@directus/sdk-js';
const directus = new DirectusSDK('https://api.example.com/', {
auth: {
storage: new MemoryStore(), // Storage adapter where refresh tokens are stored in JSON mode
mode: 'json', // What login mode to use. One of `json`, `cookie`
autoRefresh: true, // Whether or not to automatically refresh the access token on login
},
});
Get / set API URL
// Get the used API base URL
console.log(directus.url);
// => https://api.example.com/
// Set the API base URL
directus.url = 'https://api2.example.com';
Access to Axios
You can tap into the Axios instance used directly through directus.axios.
Items
Create
Single Item
directus.items('articles').create({
title: 'My New Article',
});
Multiple Items
directus.items('articles').create([
{
title: 'My First Article',
},
{
title: 'My Second Article',
},
]);
Read
All
directus.items('articles').read();
By Query
directus.items('articles').read({
search: 'Directus',
filter: {
date_published: {
_gte: '$NOW',
},
},
});
By Primary Key(s)
// One
directus.items('articles').read(15);
// Multiple
directus.items('articles').read([15, 42]);
Supports optional query:
// One
directus.items('articles').read(15, { fields: ['title'] });
// Multiple
directus.items('articles').read([15, 42], { fields: ['title'] });
Update
One or More Item(s), Single Value
// One
directus.items('articles').update(15, {
title: 'An Updated title',
});
// Multiple
directus.items('articles').update([15, 42], {
title: 'An Updated title',
});
Supports optional query:
directus.items('articles').update(15, { title: 'An Updated title' }, { fields: ['title'] });
directus.items('articles').update([15, 42], { title: 'An Updated title' }, { fields: ['title'] });
Multiple Items, Multiple Values
directus.items('articles').update([
{
id: 15,
title: 'Article 15',
},
{
id: 42,
title: 'Article 42',
},
]);
Supports optional query:
directus.items('articles').update(
[
{
id: 15,
title: 'Article 15',
},
{
id: 42,
title: 'Article 42',
},
],
{ fields: ['title'] }
);
Multiple Items by Query, Single Value
directus.items('articles').update(
{
archived: true,
},
{
filter: {
publish_date: {
_gte: '$NOW',
},
},
}
);
Delete
// One
directus.items('articles').delete(15);
// Multiple
directus.items('articles').delete([15, 42]);
Activity
Read Activity
All
directus.activity.read();
By Query
directus.activity.read({
filter: {
action: {
_eq: 'create',
},
},
});
By Primary Key(s)
// One
directus.activity.read(15);
// Multiple
directus.activity.read([15, 42]);
Supports optional query:
// One
directus.activity.read(15, { fields: ['action'] });
// Multiple
directus.activity.read([15, 42], { fields: ['action'] });
Create a Comment
directus.activity.comments.create({
collection: 'articles',
item: 15,
comment: 'Hello, world!',
});
Update a comment
directus.activity.comments.update(31, { comment: 'Howdy, world!' });
Note: The passed key is the primary key of the comment
Delete a comment
directus.activity.comments.delete(31);
Note: The passed key is the primary key of the comment
Auth
Configuration
Note: these configuration options are passed in the top level SDK constructor.
mode
cookie or json. When in cookie mode, the API will set the refresh token in a httpOnly secure
cookie that can't be accessed from client side JS. This is the most secure way to connect to the API
from a public front-end website.
When you can't rely on cookies, or need more control over handling the storage of the cookie, use
json mode. This will return the refresh token like "regular" in the payload. You can use the
storage option (see below) to control where the refresh token is stored / read from
storage
When using json for mode, the refresh token needs to be stored somewhere. The storage option
allows you to plug in any object that has an async setItem() and getItem() method. This allows
you to plugin things like localforage directly:
import localforage from 'localforage';
import DirectusSDK from '@directus/sdk-js';
const directus = new DirectusSDK('https://api.example.com', { storage: localforage });
autoRefresh
Whether or not to automatically call refresh() when the access token is about to expire. Defaults
to true
Get / Set Token
directus.auth.token = 'abc.def.ghi';
Login
directus.auth.login({ email: 'admin@example.com', password: 'd1r3ctu5' });
Refresh
Note: if you have autoRefresh enabled, you most likely won't need to use this manually.
directus.auth.refresh();
Logout
directus.auth.logout();
Request a Password Reset
directus.auth.password.request('admin@example.com');
Reset a Password
directus.auth.password.reset('abc.def.ghi', 'n3w-p455w0rd');
Note: the token passed in the first parameter is sent in an email to the user when using request()
Collections
directus.collections;
Same methods as directus.items(collection).
Fields
directus.fields;
Same methods as directus.items(collection).
Files
directus.files;
Same methods as directus.items(collection).
Folders
directus.folders;
Same methods as directus.items(collection).
Permissions
directus.permissions;
Same methods as directus.items(collection).
Presets
directus.presets;
Same methods as directus.items(collection).
Relations
directus.relations;
Same methods as directus.items(collection).
Revisions
directus.revisions;
Same methods as directus.items(collection).
Roles
directus.roles;
Same methods as directus.items(collection).
Server
Get the API Spec in OAS Format
directus.server.specs.oas();
Ping the Server
directus.server.ping();
Get Server/Project Info
directus.server.info();
Settings
directus.settings;
Same methods as directus.items(collection).
Users
directus.users;
Same methods as directus.items(collection), and:
Invite a New User
directus.users.invite('admin@example.com', 'fe38136e-52f7-4622-8498-112b8a32a1e2');
The second parameter is the role of the user
Accept a User Invite
directus.users.acceptInvite('abc.def.ghi', 'n3w-p455w0rd');
The provided token is sent to the user's email
Enable Two-Factor Authentication
directus.users.tfa.enable('my-password');
Disable Two-Factor Authentication
directus.users.tfa.disable('691402');
Get the Current User
directus.users.me.read();
Supports optional query:
directus.users.me.read({
fields: ['last_access'],
});
Update the Current Users
directus.users.me.update({ first_name: 'Admin' });
Supports optional query:
directus.users.me.update({ first_name: 'Admin' }, { fields: ['last_access'] });
Utils
Get a Random String
directus.utils.random.string();
Supports an optional length:
directus.utils.random.string(32);
Generate a Hash for a Given Value
directus.utils.hash.generate('My String');
Verify if a Hash is Valid
directus.utils.hash.verify('My String', '$argon2i$v=19$m=4096,t=3,p=1$A5uogJh');
Sort Items in a Collection
directus.utils.sort('articles', 15, 42);
This will move item 15 to the position of item 42, and move everything in between one "slot" up
Revert to a Previous Revision
directus.utils.revert(451);
Note: the key passed is the primary key of the revision you'd like to apply