tabshift/payload
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: formatting tweaks for local api docs (#12064)

Browse Source 
More formatting cleanup for new Local API / server function docs.
This commit is contained in:
Jessica Chowdhury
2025-04-09 17:01:29 +01:00
committed by GitHub
parent d19412f62d
commit a90ae9d42b
2 changed files with 21 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/local-api/access-control.mdx
View File

@@ -6,11 +6,9 @@ desc: Learn how to implement and enforce access control in Payload's Local API o
keywords: server functions, local API, Payload, CMS, access control, permissions, user context, server-side logic, custom workflows, data management, headless CMS, TypeScript, Node.js, backend keywords: server functions, local API, Payload, CMS, access control, permissions, user context, server-side logic, custom workflows, data management, headless CMS, TypeScript, Node.js, backend
--- ---
## Understanding Access Control in Local API Operations
In Payload, local API operations **override access control by default**. This means that operations will run without checking if the current user has permission to perform the action. This is useful in certain scenarios where access control is not necessary, but it is important to be aware of when to enforce it for security reasons. In Payload, local API operations **override access control by default**. This means that operations will run without checking if the current user has permission to perform the action. This is useful in certain scenarios where access control is not necessary, but it is important to be aware of when to enforce it for security reasons.
### **Default Behavior: Access Control Skipped** ### Default Behavior: Access Control Skipped
By default, **local API operations skip access control**. This allows operations to execute without the system checking if the current user has appropriate permissions. This might be helpful in admin or server-side scripts where the user context is not required to perform the operation. By default, **local API operations skip access control**. This allows operations to execute without the system checking if the current user has appropriate permissions. This might be helpful in admin or server-side scripts where the user context is not required to perform the operation.
@@ -27,12 +25,12 @@ const test = await payload.create({
}) })
``` ```
### **Respecting Access Control** ### Respecting Access Control
If you want to **respect access control** and ensure that the operation is performed only if the user has appropriate permissions, you need to explicitly pass the `user` object and set the `overrideAccess` option to `false`. If you want to respect access control and ensure that the operation is performed only if the user has appropriate permissions, you need to explicitly pass the `user` object and set the `overrideAccess` option to `false`.
- **`overrideAccess: false`**: This ensures that access control is **not skipped** and the operation respects the current user's permissions. - `overrideAccess: false`: This ensures that access control is **not skipped** and the operation respects the current user's permissions.
- **`user`**: Pass the authenticated user context to the operation. This ensures the system checks whether the user has the right permissions to perform the action. - `user`: Pass the authenticated user context to the operation. This ensures the system checks whether the user has the right permissions to perform the action.
```ts ```ts
const authedCreate = await payload.create({ const authedCreate = await payload.create({

32
docs/local-api/server-functions.mdx
View File

@@ -19,7 +19,7 @@ In Next.js, **server functions** (previously called **server actions**) are spec
Use server functions whenever you need to call Local API operations from the frontend. Since the Local API is only accessible from the backend, server functions act as a secure bridge, eliminating the need to expose additional API endpoints. Use server functions whenever you need to call Local API operations from the frontend. Since the Local API is only accessible from the backend, server functions act as a secure bridge, eliminating the need to expose additional API endpoints.
## Examples: Using Local API from Server Functions ## Examples
All Local API operations can be used within server functions, allowing you to interact with Payload's backend securely. All Local API operations can be used within server functions, allowing you to interact with Payload's backend securely.
@@ -63,7 +63,7 @@ export async function createPost(data) {
} }
``` ```
Now, let's look at how to call the \`createPost\` function we just created from the frontend in a React component when a user clicks a button: Now, let's look at how to call the `createPost` function we just created from the frontend in a React component when a user clicks a button:
```ts ```ts
'use client'; 'use client';
@@ -123,7 +123,7 @@ export async function updatePost(id, data) {
} }
``` ```
Here is how you would call the \`updatePost\` function from a frontend React component: Here is how you would call the `updatePost` function from a frontend React component:
```ts ```ts
'use client'; 'use client';
@@ -158,8 +158,8 @@ export const UpdatePostForm: React.FC = () => {
In this example, we will check if a user is authenticated using Payload's authentication system. Here's how it works: In this example, we will check if a user is authenticated using Payload's authentication system. Here's how it works:
- First, we use the headers function from next/headers to retrieve the request headers. - First, we use the headers function from `next/headers` to retrieve the request headers.
- Next, we pass these headers to payload.auth() to fetch the user's authentication details. - Next, we pass these headers to `payload.auth()` to fetch the user's authentication details.
- If the user is authenticated, their information is returned. If not, handle the unauthenticated case accordingly. - If the user is authenticated, their information is returned. If not, handle the unauthenticated case accordingly.
Here's the server function to authenticate a user: Here's the server function to authenticate a user:
@@ -220,9 +220,9 @@ export const AuthComponent: React.FC = () => {
This example demonstrates how to write a server function that creates a document with a file upload. Here are the key steps: This example demonstrates how to write a server function that creates a document with a file upload. Here are the key steps:
- Pass two arguments: data for the document content and upload for the file - Pass two arguments: **data** for the document content and **upload** for the file
- Merge the upload file into the document data as the media field - Merge the upload file into the document data as the media field
- Use payload.create() to create a new post document with both the document data and file - Use `payload.create()` to create a new post document with both the document data and file
```ts ```ts
'use server' 'use server'
@@ -255,9 +255,9 @@ export async function createPostWithUpload(data, upload) {
Here is how you would use the server function we just created in a frontend component to allow users to submit a post along with a file upload: Here is how you would use the server function we just created in a frontend component to allow users to submit a post along with a file upload:
- The user enters the post title and selects a file to upload. - The user enters the post title and selects a file to upload.
- When the form is submitted, the handleSubmit function checks if a file has been chosen. - When the form is submitted, the `handleSubmit` function checks if a file has been chosen.
- If a file is selected, it passes both the title and the file to the createPostWithFile server function. - If a file is selected, it passes both the title and the file to the `createPostWithFile` server function.
- And you are done\! - And you are done!
```ts ```ts
'use client'; 'use client';
@@ -318,9 +318,9 @@ When using server functions, proper error handling is essential to prevent unhan
### Best Practices#error-handling-best-practices ### Best Practices#error-handling-best-practices
- **Wrap Local API calls in try/catch blocks** to catch potential errors. - Wrap Local API calls in **try/catch blocks** to catch potential errors.
- **Log errors on the server** for debugging purposes. - **Log errors** on the server for debugging purposes.
- **Return structured error responses** instead of exposing raw errors to the frontend. - Return structured **error responses** instead of exposing raw errors to the frontend.
Example of good error handling: Example of good error handling:
@@ -342,9 +342,9 @@ Using server functions helps prevent direct exposure of Local API operations to
### Best Practices#security-best-practices ### Best Practices#security-best-practices
1. **Restrict access**: Ensure that sensitive actions (like user management) are only callable by authorized users. - **Restrict access**: Ensure that sensitive actions (like user management) are only callable by authorized users.
2. **Avoid passing sensitive data**: Do not return sensitive information such as user data, passwords, etc. - **Avoid passing sensitive data**: Do not return sensitive information such as user data, passwords, etc.
3. **Use authentication & authorization**: Check user roles before performing actions. - **Use authentication & authorization**: Check user roles before performing actions.
Example of restricting access based on user role: Example of restricting access based on user role: