From f9886a5b9fa23055390349a941c238ffe5d53a4d Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 3 May 2023 17:16:08 +0300 Subject: [PATCH] docs: added manage users documentation (#4000) * docs: added manage users documentation * fix link --- .../modules/users/admin/manage-profile.mdx | 6 + .../modules/users/admin/manage-users.mdx | 365 ++++++++++++++++++ docs/content/modules/users/overview.mdx | 3 +- www/docs/sidebars.js | 7 +- 4 files changed, 374 insertions(+), 7 deletions(-) create mode 100644 docs/content/modules/users/admin/manage-users.mdx diff --git a/docs/content/modules/users/admin/manage-profile.mdx b/docs/content/modules/users/admin/manage-profile.mdx index 4dd60afbb7..d8ba2b5205 100644 --- a/docs/content/modules/users/admin/manage-profile.mdx +++ b/docs/content/modules/users/admin/manage-profile.mdx @@ -520,3 +520,9 @@ This endpoint requires the following request body parameters: You can also optionally pass the `email` parameter in the request body. The request returns the user as an object, and the user is automatically logged in. + +--- + +## See Also + +- [How to manage users](./manage-users.mdx) diff --git a/docs/content/modules/users/admin/manage-users.mdx b/docs/content/modules/users/admin/manage-users.mdx new file mode 100644 index 0000000000..28e28a5492 --- /dev/null +++ b/docs/content/modules/users/admin/manage-users.mdx @@ -0,0 +1,365 @@ +--- +description: 'Learn how to manage users using the admin APIs. This includes listing, creating, updating, and deleting users.' +addHowToData: true +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# How to Manage Users + +In this document, you’ll learn how to manage users using the admin APIs. + +## Overview + +You can use the user admin API to manage users and teams in the store. + +### Scenario + +You want to add or use the following admin functionalities: + +- List users +- Create a user +- Update a user +- Delete a user + +--- + +## Prerequisites + +### Medusa Components + +It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../../development/backend/install.mdx) to get started. + +### JS Client + +This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. + +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration). + +### Medusa React + +This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods. + +If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage). + +### Authenticated Admin User + +You must be an authenticated admin user before following along with the steps in the tutorial. + +You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication). + +--- + +## List Users + +You can retrieve users in a store by sending a request to the [List Users endpoint](/api/admin#tag/Users/operation/GetUsers): + + + + +```ts +medusa.admin.users.list() +.then(({ users }) => { + console.log(users.length) +}) +``` + + + + +```tsx +import { useAdminUsers } from "medusa-react" + +const Users = () => { + const { users, isLoading } = useAdminUsers() + + return ( +
+ {isLoading && Loading...} + {users && !users.length && No Users} + {users && users.length > 0 && ( +
    + {users.map((user) => ( +
  • {user.email}
    • + ))} +
+ )} +
+ ) +} + +export default Users +``` + + + + +```ts +fetch(`/admin/users`, { + credentials: "include", +}) +.then((response) => response.json()) +.then(({ users }) => { + console.log(users.length) +}) +``` + + + + +```bash +curl -L -X GET '/admin/users' \ +-H 'Authorization: Bearer ' +``` + + + + +This endpoint does not require any parameters. + +The request returns an array of user objects. + +--- + +## Create a User + +You can create a user by sending a request to the [Create User endpoint](/api/admin#tag/Users/operation/PostUsers): + + + + +```ts +medusa.admin.users.create({ + email: "user@example.com", + password: "supersecret", +}) +.then(({ user }) => { + console.log(user.id) +}) +``` + + + + +```tsx +import { useAdminCreateUser } from "medusa-react" + +const CreateUser = () => { + const createUser = useAdminCreateUser() + // ... + + const handleCreateUser = () => { + createUser.mutate({ + email: "user@example.com", + password: "supersecret", + }) + } + + // ... +} + +export default CreateUser +``` + + + + +```ts +fetch(`/admin/users`, { + credentials: "include", + method: "POST", + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify({ + email: "user@example.com", + password: "supersecret", + }), +}) +.then((response) => response.json()) +.then(({ user }) => { + console.log(user.id) +}) +``` + + + + +```bash +curl -L -X POST '/admin/users' \ +-H 'Authorization: Bearer ' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "email": "user@example.com", + "password": "supersecret" +}' +``` + + + + +This endpoint requires the following request body parameters: + +- `email`: a string indicating the email of the user. +- `password`: a string indicating the password of the user. + +The endpoint accepts other optional body parameters, such as first name or last name. Check the [API reference](/api/admin#tag/Users/operation/PostUsers) for details on optional body parameters. + +The request returns the created user as an object. + +--- + +## Update User + +You can update a user’s details by sending a request to the [Update User endpoint](/api/admin#tag/Users/operation/PostUsersUser): + + + + +```ts +medusa.admin.users.update(userId, { + first_name: "Marcellus", +}) +.then(({ user }) => { + console.log(user.id) +}) +``` + + + + +```tsx +import { useAdminUpdateUser } from "medusa-react" + +const UpdateUser = () => { + const updateUser = useAdminUpdateUser(userId) + // ... + + const handleUpdateUser = () => { + updateUser.mutate({ + first_name: "Marcellus", + }) + } + + // ... +} + +export default UpdateUser +``` + + + + +```ts +fetch(`/admin/users/${userId}`, { + credentials: "include", + method: "POST", + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify({ + first_name: "Marcellus", + }), +}) +.then((response) => response.json()) +.then(({ user }) => { + console.log(user.id) +}) +``` + + + + +```bash +curl -L -X POST '/admin/users/' \ +-H 'Authorization: Bearer ' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "first_name": "Marcellus" +}' +``` + + + + +This endpoint requires the ID of the user as a path parameter. + +In the request body, you can pass any of the user’s fields that you want to update as parameters. In the example above, you update the user’s `first_name`. Check the [API reference](/api/admin#tag/Users/operation/PostUsersUser) for all the optional parameters. + +The request returns the updated user as an object. + +--- + +## Delete a User + +You can delete a user by sending a request to the [Delete User endpoint](/api/admin#tag/Users/operation/DeleteUsersUser): + + + + +```ts +medusa.admin.users.delete(userId) +.then(({ id, object, deleted }) => { + console.log(id) +}) +``` + + + + +```tsx +import { useAdminDeleteUser } from "medusa-react" + +const DeleteUser = () => { + const deleteUser = useAdminDeleteUser(userId) + // ... + + const handleDeleteUser = () => { + deleteUser.mutate() + } + + // ... +} + +export default DeleteUser +``` + + + + +```ts +fetch(`/admin/users/${userId}`, { + credentials: "include", + method: "DELETE", +}) +.then((response) => response.json()) +.then(({ id, object, deleted }) => { + console.log(id) +}) +``` + + + + +```bash +curl -L -X DELETE '/admin/users/' \ +-H 'Authorization: Bearer ' +``` + + + + +This endpoint requires the user ID as a path parameter. + +This request requires the user ID as a path parameter. It deletes the user and returns the following fields: + +- `id`: The ID of the deleted user. +- `object`: The type of object that was deleted. In this case, the value will be `user`. +- `deleted`: A boolean value indicating whether the user was deleted. + +--- + +## See Also + +- [How to manage a user’s profile](./manage-profile.mdx) diff --git a/docs/content/modules/users/overview.mdx b/docs/content/modules/users/overview.mdx index 7dcce274b3..0156741501 100644 --- a/docs/content/modules/users/overview.mdx +++ b/docs/content/modules/users/overview.mdx @@ -27,12 +27,11 @@ Admins can also manage their profile details.