1 of 12

API How-Tos

Network File Storage APIs allow contract owners, administrators, and authenticated users with the required permissions to create clusters and shares within the storage system via the API.

Quick Links

Endpoint

Use the regional endpoints to interact with Network File Storage:

Berlin, Germany: https://nfs.de-txl.ionos.com
Frankfurt, Germany: https://nfs.de-fra.ionos.com

Authentication

The API uses the following two authentication methods:

Basic Authentication: Ensure that the string containing your username and password is base64-encoded and separated by a colon: username@domain.tld:password.
Token Authentication: Provide a header value as Bearer followed by your token.

Important: From March 15, 2024, the Basic Authentication option will only be accessible if the 2-factor Authentication (2FA) is disabled for your account.

Set User Privileges via the API

Prerequisite: You need administrative privileges to create and assign user privileges using the Cloud API.

To set user privileges via the Cloud API to access and manage shares and Network File Storage clusters, follow these steps:

Authenticate to the Cloud API using your API credentials.
Create a user using the POST /cloudapi/v6/um/users endpoint.
Set the following required parameters for the user: user's name, email address, and password.
Create a group using the POST /cloudapi/v6/um/groups endpoint.
Set accessAndManageNFS privilege to true.
Assign the user to the created group using POST /cloudapi/v6/um/groups/{groupId}/users endpoint.

Note: Remember to provide the user ID in the request body: id: <userID>

Result: The user has the privilege to access and manage Network File Storage.

Create Cluster

To create a Network File Storage cluster via the API, perform a POST request with the name and description of the cluster.

Prerequisites:

Only contract administrators, owners, and users with accessAndManageNFS privileges can create and manage clusters.

Endpoint

Use the regional endpoints to create a cluster:

https://nfs.de-txl.ionos.com/clusters
https://nfs.de-fra.ionos.com/clusters

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

curl -X 'POST' \
  'https://nfs.de-txl.ionos.com/clusters' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {},
  "properties": {
    "name": "Cluster 1",
    "connections": [
      {
        "datacenterId": "123e4567-e89b-12d3-a456-426614174001",
        "lan": "1",
        "ipAddress": "10.254.64.1/24"
      }
    ],
    "nfs": {
      "minVersion": "4.2"
    },
    "size": 8
  }
}'

To make authenticated requests to the API, the following fields are mandatory in the request header:

Below is the list of mandatory body parameters:

Response

A 201 message confirms that the cluster creation is successful.

{
  "id": "e69b22a5-8fee-56b1-b6fb-4a07e4205ead",
  "type": "cluster",
  "href": "/clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null
  },
  "properties": {
    "name": "Cluster 1",
    "connections": [
      {
        "datacenterId": "123e4567-e89b-12d3-a456-426614174001",
        "lan": "1",
        "ipAddress": "10.254.64.1/24"
      }
    ],
    "nfs": {
      "minVersion": "4.2"
    },
    "size": 8
  }
} ```

Retrieve Cluster

You can retrieve the information about a specific cluster using its clusterId.

Endpoint

Use the regional endpoints to retrieve a specific cluster:

https://nfs.de-txl.ionos.com/clusters/{clusterId}
https://nfs.de-fra.ionos.com/clusters/{clusterId}

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

To make authenticated requests to the API, the following fields are mandatory in the request header:

Header Parameters

Required

Type

Description

Below is the list of mandatory path parameter:

Body Parameters

Type

Description

Example

Response

A 200 message confirms that the specific cluster information is successfully retrieved.

Retrieve Clusters

You can retrieve a list of all Network File Storage clusters in your contract. The number of results displayed on each page depends on the following values:

limit limits the number of response elements.
offset specifies the starting point within the collection of resource results returned from the server.

Additionally, you can also use a response filter (filter.datacenterId) to list only the clusters within the specified data center.

Endpoint

Use the regional endpoints to retrieve all clusters:

https://nfs.de-txl.ionos.com/clusters
https://nfs.de-fra.ionos.com/clusters

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

curl -X 'GET' \
  'https://nfs.de-txl.ionos.com/clusters?offset=0&limit=100' \
  -H 'accept: application/json'

To make authenticated requests to the API, the following fields are mandatory in the request header:

Header Parameters

Required

Type

Description

Response

A 200 message confirms that a list of clusters is fetched.

{
  "id": "ed17eb1f-ac43-5670-9e63-8be33c475449",
  "type": "collection",
  "href": "/clusters",
  "items": [
    {
      "id": "e69b22a5-8fee-56b1-b6fb-4a07e4205ead",
      "type": "cluster",
      "href": "/clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead",
      "metadata": {
        "createdDate": "2020-12-10T13:37:50+01:00",
        "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "lastModifiedDate": "2020-12-11T13:37:50+01:00",
        "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
        "status": "AVAILABLE",
        "statusMessage": null
      },
      "properties": {
        "name": "Cluster 1",
        "connections": [
          {
            "datacenterId": "123e4567-e89b-12d3-a456-426614174001",
            "lan": "1",
            "ipAddress": "10.254.64.1/24"
          }
        ],
        "nfs": {
          "minVersion": "4.2"
        },
        "size": 8
      }
    }
  ],
  "offset": 0,
  "limit": 42,
  "_links": {
    "prev": "http://PREVIOUS-PAGE-URI",
    "self": "http://THIS-PAGE-URI",
    "next": "http://NEXT-PAGE-URI"
  }
} ```

Update Cluster

You can append a cluster, or update the content of an existing cluster within your Network File Storage using the PUT API request.

Endpoint

Use the regional endpoints to update a cluster:

https://nfs.de-txl.ionos.com/clusters/{clusterId}
https://nfs.de-fra.ionos.com/clusters/{clusterId}

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

curl -X 'PUT' \
  'https://nfs.de-fra.ionos.com/clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "e69b22a5-8fee-56b1-b6fb-4a07e4205ead",
  "metadata": {},
  "properties": {
    "name": "Cluster 1",
    "connections": [
      {
        "datacenterId": "123e4567-e89b-12d3-a456-426614174001",
        "lan": "1",
        "ipAddress": "10.254.64.1/24"
      }
    ],
    "nfs": {
      "minVersion": "4.2"
    },
    "size": 8
  }
}'

To make authenticated requests to the API, the following fields are mandatory in the request header:

Response

A 200 message confirms that the specified cluster is successfully updated.

{
 {
  "id": "ed17eb1f-ac43-5670-9e63-8be33c475449",
  "type": "collection",
  "href": "/clusters",
  "items": [
    {
      "id": "e69b22a5-8fee-56b1-b6fb-4a07e4205ead",
      "type": "cluster",
      "href": "/clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead",
      "metadata": {
        "createdDate": "2020-12-10T13:37:50+01:00",
        "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "lastModifiedDate": "2020-12-11T13:37:50+01:00",
        "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
        "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
        "status": "AVAILABLE",
        "statusMessage": null
      },
      "properties": {
        "name": "Cluster 1",
        "connections": [
          {
            "datacenterId": "123e4567-e89b-12d3-a456-426614174001",
            "lan": "1",
            "ipAddress": "10.254.64.1/24"
          }
        ],
        "nfs": {
          "minVersion": "4.2"
        },
        "size": 8
      }
    }
  ],
  "offset": 0,
  "limit": 42,
  "_links": {
    "prev": "http://PREVIOUS-PAGE-URI",
    "self": "http://THIS-PAGE-URI",
    "next": "http://NEXT-PAGE-URI"
  }
}
} ```

Delete Cluster

You can delete a specific cluster using its clusterId.

Prerequisite: Only contract administrators, owners, and users with accessAndManageNFS privilege can delete clusters via the API.

Endpoint

Use the regional endpoints to delete a cluster:

https://nfs.de-txl.ionos.com/clusters/{clusterId}
https://nfs.de-fra.ionos.com/clusters/{clusterId}

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

curl -X 'DELETE' \
  'https://nfs.de-txl.ionos.com/clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead' \
  -H 'accept: application/json'
  -H 'Authorization: Basic <auth-token>'

To make authenticated requests to the API, the following fields are mandatory in the request header:

Header Parameters

Required

Type

Description

Below is the list of mandatory path parameter:

Body Parameters

Type

Description

Example

Response

A 202 message confirms that the specified cluster has been successfully deleted.

Create Share

To create a share within the Network File Storage's cluster, via the API, perform a POST request with the clusterId. The request automatically creates a share within the respective cluster.

Prerequisites:

Only contract administrators, owners, and users with accessAndManageNFS privileges can create and manage clusters.

Endpoint

Use the regional endpoints to create a share:

https://nfs.de-txl.ionos.com/clusters/{clusterId}/shares
https://nfs.de-fra.ionos.com/clusters/{clusterId}/shares

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

curl -X 'POST' \
  'https://nfs.de-txl.ionos.com/clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead/shares' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {},
  "properties": {
    "name": "example-export",
    "quota": 512,
    "clientGroups": [
      {
        "ipNetworks": [
          "10.234.50.0/24"
        ],
        "hosts": [
          "10.234.62.123"
        ],
        "nfs": {
          "squash": "all-anonymous"
        }
      }
    ]
  }
}'

To make authenticated requests to the API, the following fields are mandatory in the request header:

Below is the list of mandatory path parameter:

Response

A 201 message confirms that the share creation is successful. Your values will differ from those in the sample code. It may contain different IDs, timestamps etc.

{
  "id": "7b1ef56d-dfc6-51fe-aff0-7af2d6747868",
  "type": "share",
  "href": "/clusters/{clusterId}/shares/7b1ef56d-dfc6-51fe-aff0-7af2d6747868",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "nfsPath": "/data/example-export"
  },
  "properties": {
    "name": "example-export",
    "quota": 512,
    "clientGroups": [
      {
        "ipNetworks": [
          "10.234.50.0/24"
        ],
        "hosts": [
          "10.234.62.123"
        ],
        "nfs": {
          "squash": "all-anonymous"
        }
      }
    ]
  }
} ```

Retrieve Share

You can retrieve the information about a specific share using its clusterId and shareId.

Endpoint

Use the regional endpoints to retrieve a specific share:

https://nfs.de-txl.ionos.com/clusters/{clusterId}/shares/{shareId}
https://nfs.de-fra.ionos.com/clusters/{clusterId}/shares/{shareId}

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

curl -X 'GET' \
  'https://nfs.de-txl.ionos.com/clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead/shares/7b1ef56d-dfc6-51fe-aff0-7af2d6747868' \
  -H 'accept: application/json'

To make authenticated requests to the API, the following fields are mandatory in the request header:

Header Parameters

Required

Type

Description

Below is the list of mandatory path parameters:

Body Parameters

Type

Description

Example

Response

A 200 message confirms that the information of the specific share from within the cluster has been successfully retrieved.

{
  "id": "7b1ef56d-dfc6-51fe-aff0-7af2d6747868",
  "type": "share",
  "href": "/clusters/{clusterId}/shares/7b1ef56d-dfc6-51fe-aff0-7af2d6747868",
  "metadata": {
    "createdDate": "2020-12-10T13:37:50+01:00",
    "createdBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "createdByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedDate": "2020-12-11T13:37:50+01:00",
    "lastModifiedBy": "ionos:identity:::users/87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "lastModifiedByUserId": "87f9a82e-b28d-49ed-9d04-fba2c0459cd3",
    "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
    "status": "AVAILABLE",
    "statusMessage": null,
    "nfsPath": "/data/example-export"
  },
  "properties": {
    "name": "example-export",
    "quota": 512,
    "clientGroups": [
      {
        "ipNetworks": [
          "10.234.50.0/24"
        ],
        "hosts": [
          "10.234.62.123"
        ],
        "nfs": {
          "squash": "all-anonymous"
        }
      }
    ]
  }
} ```

Retrieve Shares

You can retrieve the list of all shares from within a cluster using its clusterId. The number of results displayed on each page depends on the following values:

limit limits the number of response elements.
offset specifies the starting point within the collection of resource results returned from the server.

Endpoint

Use the regional endpoints to retrieve all shares:

https://nfs.de-txl.ionos.com/clusters/{clusterId}/shares
https://nfs.de-fra.ionos.com/clusters/{clusterId}/shares

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

To make authenticated requests to the API, the following fields are mandatory in the request header:

Header Parameters

Required

Type

Description

Below is the list of mandatory path parameter:

Body Parameters

Type

Description

Example

Response

A 200 message confirms that all shares from within the specific cluster are successfully retrieved.

Update Share

You can append or update the content of an existing share within your Network File Storage using the PUT API request.

Endpoint

Use the regional endpoints to update a share:

https://nfs.de-txl.ionos.com/clusters/{clusterId}/shares/{shareId}
https://nfs.de-fra.ionos.com/clusters/{clusterId}/shares/{shareId}

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

To make authenticated requests to the API, the following fields are mandatory in the request header:

Response

A 200 message confirms that the corresponding share within the specified cluster has been successfully updated.

Delete Share

You can delete a specific share from within a cluster using its clusterId and shareId.

Prerequisite: Only contract administrators, owners, and users with accessAndManageNFS privilege can delete shares via the API.

Endpoint

Use the regional endpoints to delete a specific share:

https://nfs.de-txl.ionos.com/clusters/{clusterId}/shares/{shareId}.
https://nfs.de-fra.ionos.com/clusters/{clusterId}/shares/{shareId}

Request

Note: The following request contains sample values. Remember to replace them with the relevant information.

curl -X 'DELETE' \
  'https://nfs.de-fra.ionos.com/clusters/e69b22a5-8fee-56b1-b6fb-4a07e4205ead/shares/7b1ef56d-dfc6-51fe-aff0-7af2d6747868' \
  -H 'accept: application/json'

To make authenticated requests to the API, the following fields are mandatory in the request header:

Header Parameters

Required

Type

Description

Below is the list of mandatory path parameters:

Body Parameters

Type

Description

Example

Response

A 202 message confirms that the specified share has been successfully deleted.