NFS API

Base URL: https://api.sparbz.cloud/api/v1

Overview

The NFS API allows you to create and manage Network File System (NFS) shares for shared storage access. Create shares, manage mount information, monitor usage, and control access permissions.

All endpoints require authentication via Bearer token or API key.

GET /nfs

List all NFS shares in your organization.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Description
status	string	Filter by status: `provisioning`, `available`, `resizing`, `deleting`
limit	integer	Number of results (default: 20, max: 100)
offset	integer	Pagination offset

Response (200 OK):

[
  {
    "id": "uuid",
    "name": "shared-data",
    "size_gb": 500,
    "used_gb": 256,
    "status": "available",
    "region": "us-east-1",
    "performance_tier": "standard",
    "export_path": "/shared-data",
    "mount_target": "nfs-xxx.sparbz.cloud",
    "protocol_version": "4.1",
    "access_count": 5,
    "created_at": "2024-10-15T10:30:00Z"
  }
]

POST /nfs

Create a new NFS share.

Request Body:

{
  "name": "string",
  "size_gb": 100,
  "performance_tier": "standard | premium | max-performance",
  "encryption": true,
  "access_points": []
}

Response (201 Created):

{
  "id": "uuid",
  "name": "shared-data",
  "size_gb": 500,
  "status": "provisioning",
  "performance_tier": "standard",
  "encryption": true,
  "created_at": "2024-11-29T10:30:00Z"
}

GET /nfs/:id

Get details of a specific NFS share.

Response (200 OK):

{
  "id": "uuid",
  "name": "shared-data",
  "size_gb": 500,
  "used_gb": 256,
  "available_gb": 244,
  "status": "available",
  "region": "us-east-1",
  "performance_tier": "standard",
  "throughput_mb_per_sec": 100,
  "iops": 3000,
  "export_path": "/shared-data",
  "mount_target": "nfs-xxx.sparbz.cloud",
  "protocol_version": "4.1",
  "encryption": true,
  "encryption_key_id": "key-xxx",
  "backup_enabled": true,
  "backup_schedule": "daily",
  "access_count": 5,
  "lifecycle_policy": "standard",
  "created_at": "2024-10-15T10:30:00Z",
  "updated_at": "2024-11-29T15:45:00Z"
}

PATCH /nfs/:id

Update NFS share settings.

Request Body:

{
  "size_gb": 1000,
  "performance_tier": "premium",
  "backup_enabled": true,
  "backup_schedule": "daily | weekly | monthly"
}

Response (200 OK):

{
  "id": "uuid",
  "name": "shared-data",
  "size_gb": 1000,
  "status": "resizing",
  "updated_at": "2024-11-29T15:45:00Z"
}

DELETE /nfs/:id

Delete an NFS share.

Response (204 No Content)

Access Control

GET /nfs/:id/access-points

List all access points for an NFS share.

Response (200 OK):

[
  {
    "id": "uuid",
    "name": "app-server",
    "type": "instance | lambda | ecs | k8s",
    "resource_id": "resource-xxx",
    "access_level": "read-write | read-only",
    "mount_path": "/mnt/shared",
    "connected": true,
    "last_accessed": "2024-11-29T15:45:00Z",
    "created_at": "2024-10-15T10:30:00Z"
  }
]

POST /nfs/:id/access-points

Create a new access point for an NFS share.

Request Body:

{
  "name": "string",
  "type": "instance | lambda | ecs | k8s",
  "resource_id": "string",
  "access_level": "read-write | read-only",
  "mount_path": "string",
  "enforce_user_identity": false,
  "posix_user_id": 1000
}

Response (201 Created):

{
  "id": "uuid",
  "name": "app-server",
  "type": "instance",
  "access_level": "read-write",
  "mount_path": "/mnt/shared",
  "created_at": "2024-11-29T10:30:00Z",
  "mount_instructions": {
    "command": "sudo mount -t nfs4 -o vers=4.1 nfs-xxx.sparbz.cloud:/shared-data /mnt/shared",
    "fstab": "nfs-xxx.sparbz.cloud:/shared-data /mnt/shared nfs4 vers=4.1,defaults 0 0"
  }
}

GET /nfs/:id/access-points/:access_id

Get details of a specific access point.

Response (200 OK):

{
  "id": "uuid",
  "name": "app-server",
  "type": "instance",
  "resource_id": "i-xxx",
  "access_level": "read-write",
  "mount_path": "/mnt/shared",
  "connected": true,
  "bytes_read_per_sec": 1024000,
  "bytes_written_per_sec": 512000,
  "active_connections": 3,
  "last_accessed": "2024-11-29T15:45:00Z",
  "created_at": "2024-10-15T10:30:00Z"
}

DELETE /nfs/:id/access-points/:access_id

Revoke access for a specific access point.

Response (204 No Content)

Mount Information

GET /nfs/:id/mount-info

Get mount information for an NFS share.

Response (200 OK):

{
  "mount_target": "nfs-xxx.sparbz.cloud",
  "export_path": "/shared-data",
  "protocol": "nfs",
  "version": "4.1",
  "mount_command": "sudo mount -t nfs4 -o vers=4.1,nfsvers=4.1 nfs-xxx.sparbz.cloud:/shared-data /mnt/shared",
  "fstab_entry": "nfs-xxx.sparbz.cloud:/shared-data /mnt/shared nfs4 vers=4.1,noresvport,hard,timeo=600,retrans=2 0 0",
  "security_groups": ["sg-xxx"],
  "required_ports": {
    "nfs": 2049,
    "portmap": 111,
    "mountd": 20048,
    "nlm": 32768
  },
  "dns_name": "nfs-shared-data.us-east-1.nfs.sparbz.cloud",
  "recommended_mount_options": [
    "nfsvers=4.1",
    "hard",
    "timeo=600",
    "retrans=2"
  ]
}

Usage and Metrics

GET /nfs/:id/usage

Get detailed usage information for an NFS share.

Response (200 OK):

{
  "share_id": "uuid",
  "total_size_gb": 500,
  "used_gb": 256,
  "available_gb": 244,
  "usage_percent": 51.2,
  "inodes_used": 45000,
  "inodes_available": 6553600,
  "file_count": 45000,
  "directory_count": 2500,
  "largest_files": [
    {
      "path": "/shared-data/backups/database.dump",
      "size_gb": 50
    }
  ],
  "snapshots": [
    {
      "id": "snap-xxx",
      "created_at": "2024-11-29T00:00:00Z",
      "size_gb": 10
    }
  ]
}

GET /nfs/:id/metrics

Get performance metrics for an NFS share.

Query Parameters:

Parameter	Type	Description
from	timestamp	Start time for metrics
to	timestamp	End time for metrics
granularity	string	`1m`, `5m`, `1h`

Response (200 OK):

{
  "share_id": "uuid",
  "metrics": [
    {
      "timestamp": "2024-11-29T15:45:00Z",
      "read_bytes_per_sec": 1024000,
      "write_bytes_per_sec": 512000,
      "read_ops_per_sec": 256,
      "write_ops_per_sec": 128,
      "active_connections": 3,
      "latency_ms": 2.5
    }
  ]
}

Snapshots

GET /nfs/:id/snapshots

List all snapshots of an NFS share.

Response (200 OK):

[
  {
    "id": "snap-xxx",
    "name": "daily-backup-2024-11-29",
    "size_gb": 10,
    "created_at": "2024-11-29T00:00:00Z",
    "retention_days": 30,
    "status": "available"
  }
]

POST /nfs/:id/snapshots

Create a snapshot of an NFS share.

Request Body:

{
  "name": "string",
  "retention_days": 30
}

Response (201 Created):

{
  "id": "snap-xxx",
  "name": "manual-snapshot-2024-11-29",
  "size_gb": 0,
  "created_at": "2024-11-29T15:45:00Z",
  "status": "pending"
}

GET /nfs/:id/snapshots/:snapshot_id

Get details of a specific snapshot.

Response (200 OK):

{
  "id": "snap-xxx",
  "name": "daily-backup-2024-11-29",
  "size_gb": 10,
  "created_at": "2024-11-29T00:00:00Z",
  "retention_days": 30,
  "status": "available",
  "can_restore": true
}

Backup and Recovery

GET /nfs/:id/backups

List all backups of an NFS share.

Response (200 OK):

[
  {
    "id": "backup-xxx",
    "name": "weekly-backup-2024-11-22",
    "size_gb": 200,
    "created_at": "2024-11-22T00:00:00Z",
    "backup_type": "incremental | full",
    "status": "available",
    "restore_points": 52
  }
]

POST /nfs/:id/backups

Create a backup of an NFS share.

Request Body:

{
  "name": "string",
  "backup_type": "full | incremental",
  "retention_days": 90,
  "backup_destination": "s3-bucket-name"
}

Response (201 Created):

{
  "id": "backup-xxx",
  "name": "manual-backup",
  "status": "in-progress",
  "created_at": "2024-11-29T15:45:00Z"
}

Error Responses

Code	Description
400	Bad Request - Invalid share name, size, or configuration
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Share or access point doesn't exist
409	Conflict - Share name already exists or size too small
429	Too Many Requests - NFS share limit reached
500	Internal Server Error

Common Use Cases

Creating a Shared Data Volume

POST /nfs
{
  "name": "team-data",
  "size_gb": 1000,
  "performance_tier": "standard",
  "encryption": true,
  "backup_enabled": true,
  "backup_schedule": "daily"
}

Mounting on Multiple Servers

# Get mount information
GET /nfs/{share_id}/mount-info

# Create access points for each server
POST /nfs/{share_id}/access-points
{
  "name": "web-server-1",
  "type": "instance",
  "resource_id": "i-xxx",
  "access_level": "read-write",
  "mount_path": "/mnt/data"
}

# Use mount command from mount-info
sudo mount -t nfs4 -o vers=4.1 nfs-xxx.sparbz.cloud:/team-data /mnt/data

Setting Up Daily Backups

PATCH /nfs/{share_id}
{
  "backup_enabled": true,
  "backup_schedule": "daily"
}

GET /nfs/{share_id}/usage
GET /nfs/{share_id}/metrics?granularity=1h&from=2024-11-28T00:00:00Z&to=2024-11-29T00:00:00Z

Overview​

Share Management​

GET /nfs​

POST /nfs​

GET /nfs/:id​

PATCH /nfs/:id​

DELETE /nfs/:id​

Access Control​

GET /nfs/:id/access-points​

POST /nfs/:id/access-points​

GET /nfs/:id/access-points/:access_id​

DELETE /nfs/:id/access-points/:access_id​

Mount Information​

GET /nfs/:id/mount-info​

Usage and Metrics​

GET /nfs/:id/usage​

GET /nfs/:id/metrics​

Snapshots​

GET /nfs/:id/snapshots​

POST /nfs/:id/snapshots​

GET /nfs/:id/snapshots/:snapshot_id​

Backup and Recovery​

GET /nfs/:id/backups​

POST /nfs/:id/backups​

Error Responses​

Common Use Cases​

Creating a Shared Data Volume​

Mounting on Multiple Servers​

Setting Up Daily Backups​

Monitoring NFS Share Usage​

Overview

Share Management

GET /nfs

POST /nfs

GET /nfs/:id

PATCH /nfs/:id

DELETE /nfs/:id

Access Control

GET /nfs/:id/access-points

POST /nfs/:id/access-points

GET /nfs/:id/access-points/:access_id

DELETE /nfs/:id/access-points/:access_id

Mount Information

GET /nfs/:id/mount-info

Usage and Metrics

GET /nfs/:id/usage

GET /nfs/:id/metrics

Snapshots

GET /nfs/:id/snapshots

POST /nfs/:id/snapshots

GET /nfs/:id/snapshots/:snapshot_id

Backup and Recovery

GET /nfs/:id/backups

POST /nfs/:id/backups

Error Responses

Common Use Cases

Creating a Shared Data Volume

Mounting on Multiple Servers

Setting Up Daily Backups

Monitoring NFS Share Usage