/locations

GET POST SYNC

List all data locations or create a new one.

GET /api/v1/locations

Alias: /list-data-locations-in-application-configuration

POST /api/v1/locations

Alias: /add-data-location-to-application-configuration

Description

A "Location" is a root directory where the application stores all its data, including wallets and configurations. These endpoints allow you to list all configured locations (GET) or add a new one (POST).

GET /locations

Retrieves a list of all configured data locations and indicates which one is currently active.

Response

Returns a `200 OK` with an array of Location objects.

Example Response

[
    {
        "path": "/Users/user/.config/CloudCoin/Default",
        "is_active": true
    },
    {
        "path": "/Volumes/External/CloudCoin_Backup",
        "is_active": false
    }
]

POST /locations

Adds a new data location to the application's configuration and creates the necessary directory structure on the file system.

Request Body

Parameter	Type	Required	Description
`path`	string	Yes	The absolute file system path for the new data location.

Response

Returns a `200 OK` with no content upon success.

Examples

JavaScript: List Locations

const apiHost = 'http://localhost:8006';

async function listLocations() {
    const response = await fetch(`${apiHost}/api/v1/locations`);
    const locations = await response.json();
    console.log('Available Locations:', locations);
}

listLocations();

JavaScript: Create a Location

async function createLocation(newPath) {
    await fetch(`${apiHost}/api/v1/locations`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ path: newPath })
    });
    console.log(`Location at "${newPath}" created.`);
}

// createLocation('/Users/user/new_cloudcoin_data');

cURL: List Locations

# List all locations
curl -X GET "http://localhost:8006/api/v1/locations"

cURL: Create a Location

# Create a new location
curl -X POST "http://localhost:8006/api/v1/locations" \
-H "Content-Type: application/json" \
-d '{"path":"/Users/user/new_data"}'

Go: List Locations

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
)

const apiHost = "http://localhost:8006/api/v1"

type Location struct {
    Path     string `json:"path"`
    IsActive bool   `json:"is_active"`
}

// listLocations retrieves all configured data locations.
func listLocations() {
    resp, err := http.Get(fmt.Sprintf("%s/locations", apiHost))
    if err != nil {
        log.Fatalf("Failed to make request: %v", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        log.Fatalf("Failed to list locations, status: %s", resp.Status)
    }

    var locations []Location
    if err := json.NewDecoder(resp.Body).Decode(&locations); err != nil {
        log.Fatalf("Failed to decode response: %v", err)
    }

    fmt.Println("Available Locations:")
    for _, loc := range locations {
        fmt.Printf("- Path: %s, Active: %t\n", loc.Path, loc.IsActive)
    }
}

Go: Create a Location

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
)

// createLocation adds a new data location.
func createLocation(path string) {
    payload, err := json.Marshal(map[string]string{"path": path})
    if err != nil {
        log.Fatalf("Failed to marshal JSON: %v", err)
    }

    resp, err := http.Post(fmt.Sprintf("%s/locations", apiHost), "application/json", bytes.NewBuffer(payload))
    if err != nil {
        log.Fatalf("Failed to make request: %v", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode == http.StatusOK {
        fmt.Printf("Location '%s' created successfully.\n", path)
    } else {
        log.Fatalf("Failed to create location, status: %s", resp.Status)
    }
}