Skip to content
Dean Hristov edited this page Dec 21, 2023 · 1 revision

This piece of the API allows you to perform the CRUD operations in the context of the carts collection

Endpoints

Users

The users are a collection (document) of items. Each item is an object, that contains the following:

{
    "_id": "091248e6-b150-4ebf-910a-ae7a59174c11",
    "username": "visitor-1",
    "name": "User Account 1",
    "email": "[email protected]",
    "role": "visitor"
}

Retrieving a list of resources

GET /api/v1/users

Returns a list of users. It require authentication!

This endpoint uses pagination to handle the returned results. Each response will indicate the total number of results, the next page or prev page, the status and the total number of pages.

Parameters

Name Type In Required Description
limit integer query No Specifies the number of items (per page), that you want to retrieve.
page integer query No Specifies the page you wish to retrive from the entire result set.

Example response:

{
    "status": "success",
    "limit": 10,
    "nextPage": 2,
    "totalRecords": 99,
    "totalPages": 10,
    "data": [
        {
            "_id": "091248e6-b150-4ebf-910a-ae7a59174c11",
            "username": "visitor-1",
            "name": "User Account 1",
            "email": "[email protected]",
            "role": "visitor"
        },
        ...
    ]
}

Status codes

Status code Description
200 OK Indicates a successful response.
401 Unauthorized Indicates that the request has not been authenticated.

Retrieving a single resource

GET /api/v1/users/:userId Returns a single item from the collection of users. It require authentication!

Parameters

Name Type In Required Description
userId string params Yes The id of the resouce

Example request body:

{
    "status": "success",
    "data": {
        "_id": "ba500896-80ca-42bd-b7f7-a743b959203e",
        "username": "visitor",
        "name": "User Account",
        "email": "[email protected]",
        "role": "visitor"
    }
}

Status codes

Status code Description
200 OK Indicates a successful response.
400 Bad Request Indicates that the parameters provided are invalid.
401 Unauthorized Indicates that the request has not been authenticated.
404 Not found Indicates that the resource is not found

Creating a new resource

POST /api/v1/users

Creating a new resource. It requires authentication!

Parameters

Name Type In Required Description
username string body Yes The username
name string body Yes The name
email string body Yes The email
role string body Yes The role. It can be "admin" or "visitor"
password string body Yes The password.

Example request body:

{
    "username": "bot-005",
    "name": "Real Name",
    "email": "[email protected]",
    "role": "visitor",
    "password": "12345"
  }

Status codes

Status code Description
201 Created Indicates that the item has been created successfully.
400 Bad Request Indicates that the parameters provided are invalid.
401 Unauthorized Indicates that the request has not been authenticated.

Updating an existing resource

PATCH /api/v1/users/:userId

Apply partial update of the record from the collection. It requires authentication!

Parameters

Name Type In Required Description
userId string params Yes The id of the resouce
username string body No The username
name string body No The name
email string body No The email
role string body No The role. It can be "admin" or "visitor"
password string body No The password.

Example request:

{
    "role": "admin",
}

Status codes

Status code Description
200 OK Indicates a successful response.
401 Unauthorized Indicates that the request has not been authenticated.
404 Not found Indicates that the resource is not found

Modify an existing resource - Not implemented yet!

PUT /api/v1/users/:userId

Updating a single record from the collection. It requires authentication!

Parameters

Name Type In Required Description
------ ------ ------ ------ ------

Example request:

{ ...}

Status codes

Status code Description
200 OK Indicates a successful response.
401 Unauthorized Indicates that the request has not been authenticated.
404 Not found Indicates that the resource is not found

Deleting an existing resource

DELETE /api/v1/users/:userId

Removing a record from the collection. It requires authentication!

Parameters

Name Type In Required Description
userId string params Yes Specifies the id of record

Status codes

Status code Description
200 OK Indicates a successful response.
401 Unauthorized Indicates that the request has not been authenticated.
404 Not found Indicates that the resource is not found

API Authentication

Some of the actions described above require authentication (Bearer token)!

Parameters

Name Type In Required Description
Authorization string header Yes The bearer token of the API client.