Skip to content

Commit a90ae9d

Browse files
authored
docs: formatting tweaks for local api docs (#12064)
More formatting cleanup for new Local API / server function docs.
1 parent d19412f commit a90ae9d

File tree

2 files changed

+21
-23
lines changed

2 files changed

+21
-23
lines changed

docs/local-api/access-control.mdx

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,9 @@ desc: Learn how to implement and enforce access control in Payload's Local API o
66
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
77
---
88

9-
## Understanding Access Control in Local API Operations
10-
119
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.
1210

13-
### **Default Behavior: Access Control Skipped**
11+
### Default Behavior: Access Control Skipped
1412

1513
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.
1614

@@ -27,12 +25,12 @@ const test = await payload.create({
2725
})
2826
```
2927

30-
### **Respecting Access Control**
28+
### Respecting Access Control
3129

32-
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`.
30+
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`.
3331

34-
- **`overrideAccess: false`**: This ensures that access control is **not skipped** and the operation respects the current user's permissions.
35-
- **`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.
32+
- `overrideAccess: false`: This ensures that access control is **not skipped** and the operation respects the current user's permissions.
33+
- `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.
3634

3735
```ts
3836
const authedCreate = await payload.create({

docs/local-api/server-functions.mdx

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ In Next.js, **server functions** (previously called **server actions**) are spec
1919

2020
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.
2121

22-
## Examples: Using Local API from Server Functions
22+
## Examples
2323

2424
All Local API operations can be used within server functions, allowing you to interact with Payload's backend securely.
2525

@@ -63,7 +63,7 @@ export async function createPost(data) {
6363
}
6464
```
6565

66-
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:
66+
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:
6767

6868
```ts
6969
'use client';
@@ -123,7 +123,7 @@ export async function updatePost(id, data) {
123123
}
124124
```
125125

126-
Here is how you would call the \`updatePost\` function from a frontend React component:
126+
Here is how you would call the `updatePost` function from a frontend React component:
127127

128128
```ts
129129
'use client';
@@ -158,8 +158,8 @@ export const UpdatePostForm: React.FC = () => {
158158

159159
In this example, we will check if a user is authenticated using Payload's authentication system. Here's how it works:
160160

161-
- First, we use the headers function from next/headers to retrieve the request headers.
162-
- Next, we pass these headers to payload.auth() to fetch the user's authentication details.
161+
- First, we use the headers function from `next/headers` to retrieve the request headers.
162+
- Next, we pass these headers to `payload.auth()` to fetch the user's authentication details.
163163
- If the user is authenticated, their information is returned. If not, handle the unauthenticated case accordingly.
164164

165165
Here's the server function to authenticate a user:
@@ -220,9 +220,9 @@ export const AuthComponent: React.FC = () => {
220220

221221
This example demonstrates how to write a server function that creates a document with a file upload. Here are the key steps:
222222

223-
- Pass two arguments: data for the document content and upload for the file
223+
- Pass two arguments: **data** for the document content and **upload** for the file
224224
- Merge the upload file into the document data as the media field
225-
- Use payload.create() to create a new post document with both the document data and file
225+
- Use `payload.create()` to create a new post document with both the document data and file
226226

227227
```ts
228228
'use server'
@@ -255,9 +255,9 @@ export async function createPostWithUpload(data, upload) {
255255
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:
256256

257257
- The user enters the post title and selects a file to upload.
258-
- When the form is submitted, the handleSubmit function checks if a file has been chosen.
259-
- If a file is selected, it passes both the title and the file to the createPostWithFile server function.
260-
- And you are done\!
258+
- When the form is submitted, the `handleSubmit` function checks if a file has been chosen.
259+
- If a file is selected, it passes both the title and the file to the `createPostWithFile` server function.
260+
- And you are done!
261261

262262
```ts
263263
'use client';
@@ -318,9 +318,9 @@ When using server functions, proper error handling is essential to prevent unhan
318318

319319
### Best Practices#error-handling-best-practices
320320

321-
- **Wrap Local API calls in try/catch blocks** to catch potential errors.
322-
- **Log errors on the server** for debugging purposes.
323-
- **Return structured error responses** instead of exposing raw errors to the frontend.
321+
- Wrap Local API calls in **try/catch blocks** to catch potential errors.
322+
- **Log errors** on the server for debugging purposes.
323+
- Return structured **error responses** instead of exposing raw errors to the frontend.
324324

325325
Example of good error handling:
326326

@@ -342,9 +342,9 @@ Using server functions helps prevent direct exposure of Local API operations to
342342

343343
### Best Practices#security-best-practices
344344

345-
1. **Restrict access**: Ensure that sensitive actions (like user management) are only callable by authorized users.
346-
2. **Avoid passing sensitive data**: Do not return sensitive information such as user data, passwords, etc.
347-
3. **Use authentication & authorization**: Check user roles before performing actions.
345+
- **Restrict access**: Ensure that sensitive actions (like user management) are only callable by authorized users.
346+
- **Avoid passing sensitive data**: Do not return sensitive information such as user data, passwords, etc.
347+
- **Use authentication & authorization**: Check user roles before performing actions.
348348

349349
Example of restricting access based on user role:
350350

0 commit comments

Comments
 (0)