Managing users and databases

Users (i.e. roles with LOGIN privileges) and databases can be created using the documented SQL commands. The API provides an alternative way to manage these objects.

Quick Links User Management:	Quick Links Database Management:
List all users	List all databases
List system users	Retrieve a single database
Retrieve a single user	Create a database
Create a user	Remove a database
Remove a user
Change the login password

Common attributes

Each response from the API will include some standard attributes for metadata and pagination (for collections) which follow the IONOS API standards. Most of these will be omitted from the response examples for brevity.

Type, ID and Pagination in collections

{
  "_links": {
    "next": "https://link-to-next-collection-page",
    "previous": "https://link-to-previous-collection-page",
    "self": "https://link-to-this-collection-page"
  },
  "href": "http://link-to-this-collection-page",
  "id": "UUID-for-this-collection-page",
  "items": [
    ...
  ],
  "limit": 100,
  "offset": 0,
  "type": "collection"
}

Type, ID and Metadata for resources

{
  "href": "https://link-to-this-resource-page",
  "id": "UUID-for-this-resource-page",
  "metadata": {
    "createdBy": "URN-of-creator",
    "createdByUserId": "UUID-of-creator",
    "createdDate": "creation-timestamp",
    "lastModifiedBy": "URN-of-actor",
    "latModifiedByUserId": "UUID-of-actor",
    "lastModifiedDate": "modification-timestamp",
    "resourceURN": "URN-for-this-resource"
  },
  "properties": {
    ...
  },
  "type": "user-or-database"
}

If a resource is:

• not created via the API, its createdBy field ends with _unmanaged_.

• a read-only system resource, its createdBy field ends with _system_.

Managing users

The endpoint for user management of a postgresql cluster is /users.

List all users

A GET request will give you a list of all users. Use the limit and offset parameters to control pagination.

curl --request GET \
    --user "[email protected]:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users

Response

{
  "id": "a580ee24-7cf1-509c-8a40-d716f1e2f187",
  "items": [
    {
      "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
      "properties": {
        "system": false,
        "username": "someuser"
      },
      "type": "user"
    }
  ],
  "limit": 100,
  "offset": 0,
  "type": "collection"
}

List system users

Set the system parameter to true to view system users too. These users are required for administration purposes and cannot be changed or deleted.

curl --request GET \
    --user "[email protected]:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users?system=true

Response

{
  "id": "c90a5396-1a43-538b-a4c8-564cd0eafc07",
  "items": [
    {
      "id": "6e209957-a468-562e-9867-2a69069044c3",
      "properties": {
        "system": true,
        "username": "ionos_cloud_admin"
      },
      "type": "user"
    },
    {
      "id": "27d4069e-4df9-56cf-8114-1a846589c73a",
      "properties": {
        "system": true,
        "username": "postgres"
      },
      "type": "user"
    },
    {
      "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
      "properties": {
        "system": false,
        "username": "someuser"
      },
      "type": "user"
    },
    {
      "id": "e1ca756d-957e-5e5b-9089-56943078f98c",
      "properties": {
        "system": true,
        "username": "standby"
      },
      "type": "user"
    }
  ],
  "limit": 100,
  "offset": 0,
  "type": "collection"
}

Retrieve a single user

A single user can be retrieved by their name using a GET request.

curl --request GET \
    --user "[email protected]:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users/someuser

Response

{
  "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
  "properties": {
    "system": false,
    "username": "someuser"
  },
  "type": "user"
}

Create a user

With the POST request, you can create a new user and set the login password.

curl --request POST \
    --user "[email protected]:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
        "properties":{
            "username": "newuser",
            "password": "pwMin10Chars"
        }
    }' \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users

Response

The created user is returned.

{
  "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
  "properties": {
    "system": false,
    "username": "newuser"
  },
  "type": "user"
}

Remove a user

Use a DELETE request to remove a user. System users cannot be deleted.

curl --request DELETE \
    --user "[email protected]:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users/someuser

Response

The response body is empty.

Change the login password

With the PATCH request, you can change the login password.

curl --request PATCH \
    --user "[email protected]:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
        "properties":{
            "password": "newMin10CharPw"
        }
    }' \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/users/someuser

Response

The updated user is returned. The password is never returned, though.

{
  "id": "b35402eb-bd7b-512d-92c9-9726db47c101",
  "properties": {
    "system": false,
    "username": "someuser"
  },
  "type": "user"
}

Managing databases

The endpoint for database management of a postgresql cluster is /databases.

List all databases

A GET request will give you a list of all databases. Use the limit and offset parameters to control pagination.

curl --request GET \
    --user "[email protected]:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/databases

Response

{
  "id": "68b29b09-20e3-5fbc-94bb-b193a2ef0d28",
  "items": [
    {
      "id": "13852d13-dd87-5973-ae2c-12ecc918ee0f",
      "properties": {
        "databasename": "postgres",
        "databaseowner": "postgres"
      },
      "type": "database"
    },
    {
      "id": "d3d34784-1d4c-505f-a4ec-e8f593098ea6",
      "properties": {
        "databasename": "template0",
        "databaseowner": "postgres"
      },
      "type": "database"
    },
    {
      "id": "44e6b542-3f75-5882-8a99-53ee43ac1d97",
      "properties": {
        "databasename": "template1",
        "databaseowner": "postgres"
      },
      "type": "database"
    }
  ],
  "limit": 100,
  "offset": 0,
  "type": "collection"
}

Retrieve a single database

A single database can be retrieved by its name using a GET request.

curl --request GET \
    --user "[email protected]:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/databases/postgres

Response

{
  "id": "13852d13-dd87-5973-ae2c-12ecc918ee0f",
  "properties": {
    "databasename": "postgres",
    "databaseowner": "postgres"
  },
  "type": "database"
}

Create a database

Use a POST request to create a new database. It must specify both the name and the owner.

curl --request POST \
    --user "[email protected]:Mb2.r5oHf-0t" \
    --header "Content-Type: application/json" \
    --data-binary '{
        "properties": {
          "databasename": "newdb",
          "databaseowner":"someuser"
        }
    }' \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/databases

Response

The created database is returned.

{
  "id":"57a27d14-3966-5f2d-94ea-2a21086e9d76",
  "properties": {
    "databasename": "newdb",
    "databaseowner":"someuser"
  },
  "type":"database"
}

Remove a database

Use a DELETE request to remove a database.

curl --request DELETE \
    --user "[email protected]:Mb2.r5oHf-0t" \
    https://api.ionos.com/databases/postgresql/clusters/498ae72f-411f-11eb-9d07-046c59cc737e/databases/newdb

Response

The response body is empty.