User API

User Schema

In JSON, a User object has the following properties:

{
    "username": "<username>",
    "password": "<password>",
    "permissions": ["PERMISSION1", "PERMISSION2"],
    "register_date": "2023-05-08T18:57:27.982479"
}

Property	Type	Limits	Description
`username`	String		User’s name. This also acts as an ID.
`password`	String	Write-only	Password in plain text.
`permissions`	List of String		List of permissions (see Table of permissions).
`register_date`	DateTime	Read-only	Time the user registered at.

User Info API

The User Info API allows managing users and their permissions.

Sachet implements the following endpoints for this API:

GET /users/<username>
PATCH /users/<username>
PUT /users/<username>
DELETE /users/<username>

GET

Requesting GET /users/<username> returns a JSON object conforming to the User schema. This contains the information about the specified username.

An example response:

{
    "permissions": [
        "CREATE",
        "DELETE",
        "LIST",
        "READ"
    ],
    "register_date": "2023-05-08T18:57:27.982479",
    "username": "user"
}

A user can only read information about themselves, unless they have the administrator permission.

PATCH

Requesting PATCH /users/<username> allows modifying some or all fields of a user. The request body is JSON conforming to the User schema. Properties may be left out: they won’t be modified.

For example, to modify a user’s permissions:

{
    "permissions": [
        "CREATE"
    ]
}

Only administrators can request this method.

PUT

Requesting PUT /users/<username> completely replaces a user’s information. The request body is JSON conforming to the User schema. No property may be left out.

For example:

{
    "permissions": [
        "CREATE"
    ],
    "password": "123",
    "username": "user"
}

Only administrators can request this method.

DELETE

Requesting DELETE /users/<username> deletes the specified user.

Only administrators can request this method.

List API

There is also a User List API:

GET /users
POST /users

This API is only accessible to administrators (see Table of permissions).

GET

GET /users is a paginated endpoint that returns a list of users.

POST

POST /users creates a new user. The request body must conform to the User schema.

The server will return a 201 Created code with a similar body to this:

{
    "status": "success",
    "url": "/users/user"
}

The url field is the URL to the new user. It can be used in further requests to manage the user’s information, or delete it.