Users

Warning

REST API described here is work in progress. It changes along with the development of Papermerge Core in master branch.

GET /users/

GET /users/

Retrieves information about all users

Request Headers
Status Codes

200 - Response Body Schema

{
  links: {
    first: string,
    last: string,
    next: string,
    prev: string
  },
  data: [  # an array of users
    { # user instance BEGIN
      type: "users",
      id: string,
      attributes: {
        username: string,
        first_name: string,
        last_name: string,
        email: string,
        is_active: boolean,
        is_staff: boolean,
        is_superuser: boolean,
        date_joined: datetime
      },
      relationships: {
        inbox_folder: {
          data: {
              type: "folders",
              id: string
          }
        },
        home_folder: {
          data: {
              type: "folders",
              id: string
          }
        }
      }
    }, # user instance END
    {
      ... user instance
    },
    ...
  ],
  meta: {
    pagination: {
        page: integer,
        pages: integer,
        count: integer
    }
  }
}

POST /users/

POST /users/

Creates a user. Note that password field is not part of this request. The only mandatory field is username.

Request Headers
Status Codes

Request Body Schema

{
  data: {
    type: "users",
    attributes: {
      username*: string,
      first_name: string,
      last_name: string,
      email: string,
      is_active: boolean,
      is_staff: boolean,
      is_superuser: boolean,
      date_joined: datetime
    }
  }
}

200 - Response Body Schema

{
  data: {
    type: "users",
    id: string,
    attributes: {
      username: string,
      first_name: string,
      last_name: string,
      email: string,
      is_active: boolean,
      is_staff: boolean,
      is_superuser: boolean,
      date_joined: datetime
    },
    relationships: {
      inbox_folder: {
        data: {
          type: "folders",
          id: string
        }
      },
      home_folder: {
        data: {
          type: "folders",
          id: string
        }
      }
    }
  }
}

Note

Upon creation, newly created user is assigned two special folders inbox and home. The IDs of these special folders is included in http the reponse (relationships field). Use can use IDs of those folders to query their content.

GET /users/{id}/

GET /users/{id}/

Retrieve information about user

Request Headers
Status Codes

200 - Response Body Schema

{
  type: "users",
  id: string,
  attributes: {
    username: string,
    first_name: string,
    last_name: string,
    email: string,
    is_active: boolean,
    is_staff: boolean,
    is_superuser: boolean,
    date_joined: datetime
  },
  relationships: {
    inbox_folder: {
      data: {
          type: "folders",
          id: string
      }
    },
    home_folder: {
      data: {
          type: "folders",
          id: string
      }
    }
  }
}

404 - Response

HTTP/1.1 404 Not Found
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "detail": "Not found.",
      "status": "404",
      "code": "not_found"
    }
  ]
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "users",
    "id": "2",
    "attributes": {
      "username": "john",
      "first_name": "",
      "last_name": "",
      "email": "john@example.com",
      "is_active": true,
      "is_staff": false,
      "is_superuser": false,
      "date_joined": "2021-12-21T10:55:18.976430Z"
    },
    "relationships": {
      "inbox_folder": {
        "data": {
            "type": "folders",
            "id": "4"
        }
      },
      "home_folder": {
        "data": {
          "type": "folders",
          "id": "5"
        }
      }
    }
  }
}

DELETE /users/{id}/

DELETE /users/{id}/

Deletes user

Request Headers
Status Codes

PATCH /users/{id}/

PATCH /users/{id}/

Updates user

Request Headers
Status Codes
  • 200 OK – on successful user update

  • 404 Not Found – when user with given ID does not exists

Request Body Schema

{
  type: "users",
  id: string,
  attributes: {
    username: string,
    first_name: string,
    last_name: string,
    email: string,
    is_active: boolean,
    is_staff: boolean,
    is_superuser: boolean,
    date_joined: datetime
  },
  relationships: {
    inbox_folder: {
      data: {
          type: "folders",
          id: string
      }
    },
    home_folder: {
      data: {
          type: "folders",
          id: string
      }
    }
  }
}

POST /users/{id}/change-password/

Note

For this endpoint Content-Type header must be application/json

POST /users/{id}/change-password/

Change user password

Request Headers
Status Codes
  • 200 OK – on successful password update

  • 404 Not Found – when user with given ID does not exists

Request Body Schema

{
  password: string
}

Request Example

POST /users/2/change-password/ HTTP/1.1
Content-Type: application/json
Host: example.com

{
  "password": "newpassword"
}

GET /users/me/

GET /users/me/

Notice the slash / at the end. Retrieves information about currently authenticated user.

reqheader Content-Type: application/json

200 - Response Body Schema

{
  data: {
    type: "users",
    id: string,
    attributes: {
      username: string,
      first_name: string,
      last_name: string,
      email: string,
      is_active: boolean,
      is_staff: boolean,
      is_superuser: boolean,
      date_joined: datetime
    },
    relationships: {
      inbox_folder: {
        data: {
            type: "folders",
            id: string
        }
      },
      home_folder: {
        data: {
            type: "folders",
            id: string
        }
      }
    }
  }
}

Note

Pay special attention to relationships part. It provides IDs of user’s home and inbox folders. With those IDs you can query content of user’s home and inbox folders via Nodes endpoint.