Skip to content

Latest commit

 

History

History
311 lines (259 loc) · 8.91 KB

overview.mdx

File metadata and controls

311 lines (259 loc) · 8.91 KB
Raw
title label order desc keywords
Local API
Overview
10
The Payload Local API allows you to interact with your database and execute the same operations that are available through REST and GraphQL within Node, directly on your server.
local api, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express

The Payload Local API gives you the ability to execute the same operations that are available through REST and GraphQL within Node, directly on your server. Here, you don't need to deal with server latency or network speed whatsoever and can interact directly with your database.

Tip:
The Local API is incredibly powerful when used with server-side rendering app frameworks like NextJS. With other headless CMS, you need to request your data from third-party servers which can add significant loading time to your server-rendered pages. With Payload, you don't have to leave your server to gather the data you need. It can be incredibly fast and is definitely a game changer.

Here are some common examples of how you can use the Local API:

  • Seeding data via Node seed scripts that you write and maintain
  • Opening custom Express routes which feature additional functionality but still rely on Payload
  • Within access control and hook functions

Accessing payload

You can gain access to the currently running payload object via two ways:

Importing it

You can import or require payload into your own files after it's been initialized, but you need to make sure that your import / require statements come after you call payload.init()—otherwise Payload won't have been initialized yet. That might be obvious. To us, it's usually not.

Example:

import payload from 'payload';

const afterChangeHook = async () => {
  const posts = await payload.find({
    collection: 'posts',
  });
}
Accessing from the req

Payload is available anywhere you have access to the Express req - including within your access control and hook functions.

Example:

const afterChangeHook = async ({ req: { payload }}) => {
  const posts = await payload.find({
    collection: 'posts',
  });
}

Local options available

You can specify more options within the Local API vs. REST or GraphQL due to the server-only context that they are executed in.

Local Option Description
collection Required for Collection operations. Specifies the Collection slug to operate against.
data The data to use within the operation. Required for create, update.
depth Control auto-population of nested relationship and upload fields.
locale Specify locale for any returned documents.
fallbackLocale Specify a fallback locale to use for any returned documents.
overrideAccess Skip access control. By default, this property is set to false.
user If you re-enable access control, you can specify a user to use against the access control checks.
showHiddenFields Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config.

There are more options available on an operation by operation basis outlined below.

Note:
By default, all access control checks are disabled in the Local API, but you can re-enable them if you'd like, as well as pass a specific user to run the operation with.

Collections

The following Collection operations are available through the Local API:

Create

// The created Post document is returned
const post = await payload.create({
  collection: 'posts', // required
  data: { // required
    title: 'sure',
    description: 'maybe',
  },
  locale: 'en',
  fallbackLocale: false,
  user: dummyUserDoc,
  overrideAccess: true,
  showHiddenFields: false,

  // If creating verification-enabled auth doc,
  // you can optionally disable the email that is auto-sent
  disableVerificationEmail: true,

  // If your collection supports uploads, you can upload
  // a file directly through the Local API by providing
  // its full, absolute file path.
  filePath: path.resolve(__dirname, './path-to-image.jpg'),
})

Find

// Result will be a paginated set of Posts.
// See /docs/queries/pagination for more.
const result = await payload.find({
  collection: 'posts', // required
  depth: 2,
  page: 1,
  limit: 10,
  where: {} // pass a `where` query here
  sort: '-title',
  locale: 'en',
  fallbackLocale: false,
  user: dummyUser,
  overrideAccess: false,
  showHiddenFields: true,
})

Find by ID

// Result will be a Post document.
const result = await payload.findByID({
  collection: 'posts', // required
  id: '507f1f77bcf86cd799439011', // required
  depth: 2,
  locale: 'en',
  fallbackLocale: false,
  user: dummyUser,
  overrideAccess: false,
  showHiddenFields: true,
})

Update

// Result will be the updated Post document.
const result = await payload.update({
  collection: 'posts', // required
  id: '507f1f77bcf86cd799439011', // required
  data: { // required
    title: 'sure',
    description: 'maybe',
  },
  depth: 2,
  locale: 'en',
  fallbackLocale: false,
  user: dummyUser,
  overrideAccess: false,
  showHiddenFields: true,

  // If your collection supports uploads, you can upload
  // a file directly through the Local API by providing
  // its full, absolute file path.
  filePath: path.resolve(__dirname, './path-to-image.jpg'),
})

Delete

// Result will be the now-deleted Post document.
const result = await payload.delete({
  collection: 'posts', // required
  id: '507f1f77bcf86cd799439011', // required
  depth: 2,
  locale: 'en',
  fallbackLocale: false,
  user: dummyUser,
  overrideAccess: false,
  showHiddenFields: true,
})

Auth Operations

If a collection has Authentication enabled, additional Local API operations will be available:

Login

// result will be formatted as follows:
// {
//   token: 'o38jf0q34jfij43f3f...', // JWT used for auth
//   user: { ... } // the user document that just logged in
//   exp: 1609619861 // the UNIX timestamp when the JWT will expire
// }

const result = await payload.login({
  collection: 'users', // required
  data: { // required
    email: 'dev@payloadcms.com',
    password: 'rip',
  },
  req: req, // pass an Express `req` which will be provided to all hooks
  res: res, // used to automatically set an HTTP-only auth cookie
  depth: 2,
  locale: 'en',
  fallbackLocale: false,
  overrideAccess: false,
  showHiddenFields: true,
})

Forgot Password

// Returned token will allow for a password reset
const token = await payload.forgotPassword({
  collection: 'users', // required
  data: { // required
    email: 'dev@payloadcms.com',
  },
  req: req, // pass an Express `req` which will be provided to all hooks
})

Reset Password

// Result will be formatted as follows:
// {
//   token: 'o38jf0q34jfij43f3f...', // JWT used for auth
//   user: { ... } // the user document that just logged in
// }
const result = await payload.forgotPassword({
  collection: 'users', // required
  data: { // required
    token: 'afh3o2jf2p3f...', // the token generated from the forgotPassword operation
  },
  req: req, // pass an Express `req` which will be provided to all hooks
  res: res, // used to automatically set an HTTP-only auth cookie
})

Unlock

// Returned result will be a boolean representing success or failure
const result = await payload.unlock({
  collection: 'users', // required
  data: { // required
    email: 'dev@payloadcms.com',
  },
  req: req, // pass an Express `req` which will be provided to all hooks
  overrideAccess: true,
})

Verify

// Returned result will be a boolean representing success or failure
const result = await payload.verify({
  collection: 'users', // required
  token: 'afh3o2jf2p3f...', // the token saved on the user as `_verificationToken`
})

Globals

The following Global operations are available through the Local API:

Find

// Result will be the Header Global.
const result = await payload.findGlobal({
  slug: 'header', // required
  depth: 2,
  locale: 'en',
  fallbackLocale: false,
  user: dummyUser,
  overrideAccess: false,
  showHiddenFields: true,
})

Update

// Result will be the updated Header Global.
const result = await payload.updateGlobal({
  slug: 'header', // required
  data: { // required
    nav: [
      {
        url: 'https://google.com',
      },
      {
        url: 'https://payloadcms.com',
      },
    ],
  },
  depth: 2,
  locale: 'en',
  fallbackLocale: false,
  user: dummyUser,
  overrideAccess: false,
  showHiddenFields: true,
})