From bbdd988715e7986d68ebf11a7b98d1abbc511fed Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 21 Aug 2025 15:35:46 +0200 Subject: [PATCH 01/10] chore: add first files. --- api/api-reference.md | 831 ++++++++++++++++++ getting-started/get-started-devops-as-code.md | 225 +++++ 2 files changed, 1056 insertions(+) create mode 100644 api/api-reference.md create mode 100644 getting-started/get-started-devops-as-code.md diff --git a/api/api-reference.md b/api/api-reference.md new file mode 100644 index 0000000000..952a21e838 --- /dev/null +++ b/api/api-reference.md @@ -0,0 +1,831 @@ +# TigerData Cloud API Reference + +A comprehensive RESTful API for managing TigerData Cloud Platform resources including VPCs, services, and read replicas. + +## Overview + +**API Version:** 1.0.0 +**Base URL:** `https://api.tigerdata.com/public/v1` +**Development URL:** `https://console.dev.timescale.com/public/api/v1` +**Local Development URL:** `http://localhost:8080/public/api/v1` + +## Authentication + +The TigerData Cloud API uses HTTP Basic Authentication. Include your access key and secret key in the Authorization header. + +### Basic Authentication +```http +Authorization: Basic +``` + +### Example +```bash +# Using cURL +curl -X GET "https://api.tigerdata.com/public/v1/projects/{project_id}/services" \ + -H "Authorization: Basic $(echo -n 'your_access_key:your_secret_key' | base64)" +``` + +### Error Responses +- **401 Unauthorized:** Invalid or missing credentials +- **403 Forbidden:** Insufficient permissions + +## Common Parameters + +### Path Parameters +- `project_id` (string): The unique identifier of the project (e.g., "rp1pz7uyae") +- `service_id` (string): The unique identifier of the service (e.g., "d1k5vk7hf2") +- `vpc_id` (string): The unique identifier of the VPC (e.g., "1234567890") +- `replica_set_id` (string): The unique identifier of the read replica set (e.g., "alb8jicdpr") +- `peering_id` (string): The unique identifier of the VPC peering connection (e.g., "1234567890") + +## VPC Management + +Virtual Private Clouds (VPCs) provide network isolation for your TigerData services. + +### List All VPCs + +```http +GET /projects/{project_id}/vpcs +``` + +Lists all Virtual Private Clouds in a project. + +**Response:** `200 OK` +```json +[ + { + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "google-europe-west1" + } +] +``` + +### Create a VPC + +```http +POST /projects/{project_id}/vpcs +``` + +Creates a new Virtual Private Cloud. + +**Request Body:** +```json +{ + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "google-europe-west1" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "google-europe-west1" +} +``` + +**Error Responses:** +- `400 Bad Request`: Invalid request parameters + +### Get a VPC + +```http +GET /projects/{project_id}/vpcs/{vpc_id} +``` + +Retrieves details of a specific VPC. + +**Response:** `200 OK` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "google-europe-west1" +} +``` + +**Error Responses:** +- `404 Not Found`: VPC not found + +### Rename a VPC + +```http +POST /projects/{project_id}/vpcs/{vpc_id}/rename +``` + +Updates the name of a specific VPC. + +**Request Body:** +```json +{ + "name": "my-renamed-vpc" +} +``` + +**Response:** `200 OK` +```json +{ + "id": "1234567890", + "name": "my-renamed-vpc", + "cidr": "10.0.0.0/16", + "region_code": "google-europe-west1" +} +``` + +**Error Responses:** +- `400 Bad Request`: Invalid request parameters +- `404 Not Found`: VPC not found + +### Delete a VPC + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id} +``` + +Deletes a specific VPC. + +**Response:** `204 No Content` + +**Error Responses:** +- `404 Not Found`: VPC not found + +## VPC Peering + +Manage peering connections between VPCs across different accounts and regions. + +### List VPC Peerings + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings +``` + +Retrieves all VPC peering connections for a given VPC. + +**Response:** `200 OK` +```json +[ + { + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "aws-us-east-1", + "peer_vpc_id": "1234567890", + "provisioned_id": "1234567890", + "status": "active", + "error_message": null + } +] +``` + +### Create VPC Peering + +```http +POST /projects/{project_id}/vpcs/{vpc_id}/peerings +``` + +Creates a new VPC peering connection. + +**Request Body:** +```json +{ + "peer_account_id": "acc-12345", + "peer_region_code": "aws-us-east-1", + "peer_vpc_id": "1234567890" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "aws-us-east-1", + "peer_vpc_id": "1234567890", + "provisioned_id": "1234567890", + "status": "pending" +} +``` + +### Get VPC Peering + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Retrieves details of a specific VPC peering connection. + +### Delete VPC Peering + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Deletes a specific VPC peering connection. + +**Response:** `204 No Content` + +## Service Management + +Manage database services including TimescaleDB, PostgreSQL, and Vector databases. + +### List All Services + +```http +GET /projects/{project_id}/services +``` + +Retrieves all services within a project. + +**Response:** `200 OK` +```json +[ + { + "service_id": "d1k5vk7hf2", + "project_id": "rp1pz7uyae", + "name": "my-production-db", + "region_code": "google-europe-west1", + "service_type": "TIMESCALEDB", + "status": "READY", + "created": "2024-01-15T10:30:00Z", + "initial_password": "a-very-secure-initial-password", + "paused": false, + "resources": [ + { + "id": "resource-1", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "gp2" + } + } + ], + "endpoint": { + "host": "my-service.com", + "port": 5432 + } + } +] +``` + +### Create a Service + +```http +POST /projects/{project_id}/services +``` + +Creates a new database service. This is an asynchronous operation. + +**Request Body:** +```json +{ + "name": "my-production-db", + "service_type": "TIMESCALEDB", + "region_code": "google-europe-west1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 +} +``` + +**Response:** `202 Accepted` +```json +{ + "service_id": "d1k5vk7hf2", + "project_id": "rp1pz7uyae", + "name": "my-production-db", + "region_code": "google-europe-west1", + "service_type": "TIMESCALEDB", + "status": "QUEUED", + "created": "2024-01-15T10:30:00Z", + "initial_password": "a-very-secure-initial-password" +} +``` + +**Service Types:** +- `TIMESCALEDB`: TimescaleDB service +- `POSTGRES`: PostgreSQL service +- `VECTOR`: Vector database service + +**Error Responses:** +- `400 Bad Request`: Invalid service configuration + +### Get a Service + +```http +GET /projects/{project_id}/services/{service_id} +``` + +Retrieves details of a specific service. + +**Response:** `200 OK` +```json +{ + "service_id": "d1k5vk7hf2", + "project_id": "rp1pz7uyae", + "name": "my-production-db", + "region_code": "google-europe-west1", + "service_type": "TIMESCALEDB", + "status": "READY", + "created": "2024-01-15T10:30:00Z", + "paused": false, + "resources": [ + { + "id": "resource-1", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "gp2" + } + } + ], + "metadata": { + "environment": "PROD" + }, + "endpoint": { + "host": "my-service.com", + "port": 5432 + }, + "connection_pooler": { + "endpoint": { + "host": "pooler.my-service.com", + "port": 5432 + } + } +} +``` + +**Service Status:** +- `QUEUED`: Service creation is queued +- `DELETING`: Service is being deleted +- `CONFIGURING`: Service is being configured +- `READY`: Service is ready for use +- `DELETED`: Service has been deleted +- `UNSTABLE`: Service is in an unstable state +- `PAUSING`: Service is being paused +- `PAUSED`: Service is paused +- `RESUMING`: Service is being resumed +- `UPGRADING`: Service is being upgraded +- `OPTIMIZING`: Service is being optimized + +### Delete a Service + +```http +DELETE /projects/{project_id}/services/{service_id} +``` + +Deletes a specific service. This is an asynchronous operation. + +**Response:** `202 Accepted` + +**Error Responses:** +- `404 Not Found`: Service not found + +### Resize a Service + +```http +POST /projects/{project_id}/services/{service_id}/resize +``` + +Changes CPU and memory allocation for a service. + +**Request Body:** +```json +{ + "cpu_millis": 2000, + "memory_gbs": 8 +} +``` + +**Response:** `202 Accepted` + +### Update Service Password + +```http +POST /projects/{project_id}/services/{service_id}/updatePassword +``` + +Sets a new master password for the service. + +**Request Body:** +```json +{ + "password": "a-very-secure-new-password" +} +``` + +**Response:** `204 No Content` + +### Set Service Environment + +```http +POST /projects/{project_id}/services/{service_id}/setEnvironment +``` + +Sets the environment type for the service. + +**Request Body:** +```json +{ + "environment": "PROD" +} +``` + +**Environment Values:** +- `PROD`: Production environment +- `DEV`: Development environment + +**Response:** `200 OK` +```json +{ + "message": "Action completed successfully." +} +``` + +### Configure High Availability + +```http +POST /projects/{project_id}/services/{service_id}/setHA +``` + +Changes the HA configuration for a service. This is an asynchronous operation. + +**Request Body:** +```json +{ + "sync_replica_count": 1, + "replica_count": 2 +} +``` + +**Response:** `202 Accepted` + +### Connection Pooler Management + +#### Enable Connection Pooler + +```http +POST /projects/{project_id}/services/{service_id}/enablePooler +``` + +Activates the connection pooler for a service. + +**Response:** `200 OK` +```json +{ + "message": "Action completed successfully." +} +``` + +#### Disable Connection Pooler + +```http +POST /projects/{project_id}/services/{service_id}/disablePooler +``` + +Deactivates the connection pooler for a service. + +**Response:** `200 OK` + +### Service VPC Operations + +#### Attach Service to VPC + +```http +POST /projects/{project_id}/services/{service_id}/attachToVPC +``` + +Associates a service with a VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` + +**Error Responses:** +- `409 Conflict`: Service already attached to a VPC + +#### Detach Service from VPC + +```http +POST /projects/{project_id}/services/{service_id}/detachFromVPC +``` + +Disassociates a service from its VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` + +### Fork a Service + +```http +POST /projects/{project_id}/services/{service_id}/forkService +``` + +Creates a new, independent service by taking a snapshot of an existing one. + +**Request Body:** +```json +{ + "name": "forked-customer-db" +} +``` + +**Response:** `202 Accepted` +```json +{ + "service_id": "new-service-id", + "name": "forked-customer-db", + "forked_from": { + "project_id": "rp1pz7uyae", + "service_id": "d1k5vk7hf2", + "is_standby": false + }, + "status": "CONFIGURING" +} +``` + +## Read Replica Sets + +Manage read replicas for improved read performance and geographical distribution. + +### List Read Replica Sets + +```http +GET /projects/{project_id}/services/{service_id}/replicaSets +``` + +Retrieves all read replica sets associated with a primary service. + +**Response:** `200 OK` +```json +[ + { + "id": "alb8jicdpr", + "name": "reporting-replica-1", + "status": "active", + "nodes": 2, + "cpu_millis": 250, + "memory_gbs": 0.5, + "metadata": { + "environment": "PROD" + }, + "endpoint": { + "host": "replica.my-service.com", + "port": 5432 + } + } +] +``` + +**Replica Set Status:** +- `creating`: Replica set is being created +- `active`: Replica set is active and ready +- `resizing`: Replica set is being resized +- `deleting`: Replica set is being deleted +- `error`: Replica set encountered an error + +### Create a Read Replica Set + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets +``` + +Creates a new read replica set. This is an asynchronous operation. + +**Request Body:** +```json +{ + "name": "my-reporting-replica", + "nodes": 2, + "cpu_millis": 250, + "memory_gbs": 0.5 +} +``` + +**Response:** `202 Accepted` +```json +{ + "id": "alb8jicdpr", + "name": "my-reporting-replica", + "status": "creating", + "nodes": 2, + "cpu_millis": 250, + "memory_gbs": 0.5 +} +``` + +### Delete a Read Replica Set + +```http +DELETE /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id} +``` + +Deletes a specific read replica set. This is an asynchronous operation. + +**Response:** `202 Accepted` + +### Resize a Read Replica Set + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/resize +``` + +Changes resource allocation for a read replica set. + +**Request Body:** +```json +{ + "cpu_millis": 500, + "memory_gbs": 1.0, + "nodes": 3 +} +``` + +**Response:** `202 Accepted` + +### Read Replica Connection Pooler + +#### Enable Replica Pooler + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler +``` + +Activates the connection pooler for a read replica set. + +**Response:** `200 OK` + +#### Disable Replica Pooler + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler +``` + +Deactivates the connection pooler for a read replica set. + +**Response:** `200 OK` + +### Set Replica Environment + +```http +POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment +``` + +Sets the environment type for a read replica set. + +**Request Body:** +```json +{ + "environment": "PROD" +} +``` + +**Response:** `200 OK` + +## Data Models + +### VPC Object +```json +{ + "id": "string", + "name": "string", + "cidr": "string", + "region_code": "string" +} +``` + +### Service Object +```json +{ + "service_id": "string", + "project_id": "string", + "name": "string", + "region_code": "string", + "service_type": "TIMESCALEDB|POSTGRES|VECTOR", + "created": "2024-01-15T10:30:00Z", + "initial_password": "string", + "paused": false, + "status": "READY|CONFIGURING|QUEUED|...", + "resources": [ + { + "id": "string", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "string" + } + } + ], + "metadata": { + "environment": "PROD|DEV" + }, + "endpoint": { + "host": "string", + "port": 5432 + }, + "connection_pooler": { + "endpoint": { + "host": "string", + "port": 5432 + } + } +} +``` + +### Peering Object +```json +{ + "id": "string", + "peer_account_id": "string", + "peer_region_code": "string", + "peer_vpc_id": "string", + "provisioned_id": "string", + "status": "string", + "error_message": "string" +} +``` + +### Read Replica Set Object +```json +{ + "id": "string", + "name": "string", + "status": "creating|active|resizing|deleting|error", + "nodes": 2, + "cpu_millis": 250, + "memory_gbs": 0.5, + "metadata": { + "environment": "PROD|DEV" + }, + "endpoint": { + "host": "string", + "port": 5432 + }, + "connection_pooler": { + "endpoint": { + "host": "string", + "port": 5432 + } + } +} +``` + +## Error Handling + +The API uses standard HTTP status codes and returns error details in JSON format. + +### Error Response Format +```json +{ + "code": "ERROR_CODE", + "message": "Human-readable error description" +} +``` + +### Common Error Codes +- `400 Bad Request`: Invalid request parameters or malformed JSON +- `401 Unauthorized`: Missing or invalid authentication credentials +- `403 Forbidden`: Insufficient permissions for the requested operation +- `404 Not Found`: Requested resource does not exist +- `409 Conflict`: Request conflicts with current resource state +- `500 Internal Server Error`: Unexpected server error + +### Example Error Response +```json +{ + "code": "INVALID_REQUEST", + "message": "The service_type field is required" +} +``` + +## Rate Limiting + +The API implements rate limiting to ensure fair usage: + +- **Development Environment**: More lenient rate limits for testing +- **Production Environment**: Strict rate limits for stability +- **Local Development**: No rate limits applied + +When rate limits are exceeded, the API returns `429 Too Many Requests` with retry information in the response headers. + +## Support and Contact + +For API support and questions: +- **Support**: [TigerData Support](https://www.tigerdata.com/contact) +- **License**: [Terms of Service](https://www.tigerdata.com/legal/terms) +- **Documentation**: This API reference follows the OpenAPI 3.0.3 specification \ No newline at end of file diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md new file mode 100644 index 0000000000..df696d561a --- /dev/null +++ b/getting-started/get-started-devops-as-code.md @@ -0,0 +1,225 @@ +--- +title: "Set up TigerData Cloud API and create your first service" +excerpt: "Configure secure authentication and create a new database service using the TigerData Cloud API" +keywords: + - authentication + - service creation + - API setup + - security +tags: + - setup + - security + - services + - authentication +--- + +# Set up TigerData Cloud API and create your first service + +Set up secure authentication for the TigerData Cloud API and create your first database service. This procedure covers credential configuration, security best practices, and service creation using the RESTful API. + +## Prerequisites + +Complete the following prerequisites before setting up the API: + +- Valid TigerData Cloud account with API access +- Project ID from your TigerData Cloud console +- API access key and secret key with appropriate permissions +- Command-line tool (cURL, HTTPie, or programming language with HTTP client) +- OpenAPI specification file for reference +- Network connectivity to TigerData Cloud API endpoints + +## Configure secure authentication + +The TigerData Cloud API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include proper authentication headers. + +### Set up API credentials + +1. Obtain your API credentials from the TigerData Cloud console: + - Access key: Your unique API identifier + - Secret key: Your private authentication token + - Project ID: The identifier for your TigerData project + +2. Store credentials securely using environment variables: + ```bash + export TIGERDATA_ACCESS_KEY="your-access-key" + export TIGERDATA_SECRET_KEY="your-secret-key" + export TIGERDATA_PROJECT_ID="your-project-id" + ``` + +3. Verify credential format: + - Access key format: Alphanumeric string (typically 10-20 characters) + - Secret key format: Base64-encoded string (typically 40-60 characters) + - Project ID format: Alphanumeric string starting with project prefix + +### Configure API endpoint + +Set the appropriate API base URL for your environment: + +```bash +# Development environment (recommended for testing) +export API_BASE_URL="https://console.dev.timescale.com/public/api/v1" + +# Production environment +export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" + +# Local development (if running local server) +export API_BASE_URL="http://localhost:8080/public/api/v1" +``` + +## Test API connection + +Verify your authentication setup and API connectivity before creating resources. + +### Perform health check + +Test the API connection using a simple health check request: + +```bash +curl -X GET "${API_BASE_URL}/healthcheck" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" +``` + +Expected response: +```json +{ + "status": "healthy", + "timestamp": "2024-01-15T10:30:00Z" +} +``` + +### Validate authentication + +Test authentication by listing existing services: + +```bash +curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" +``` + +Successful authentication returns a JSON array of services (may be empty for new projects). + +## Create your first service + +Create a new database service using the TigerData Cloud API with secure configuration. + +### Prepare service configuration + +1. Define the service creation payload in JSON format: + ```json + { + "name": "my-first-service", + "service_type": "TIMESCALEDB", + "region_code": "google-europe-west1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 + } + ``` + +2. Save the configuration to a file for reuse: + ```bash + cat > service-config.json << 'EOF' + { + "name": "my-first-service", + "service_type": "TIMESCALEDB", + "region_code": "google-europe-west1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 + } + EOF + ``` + +### Submit service creation request + +1. Create the service using the POST endpoint: + ```bash + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d @service-config.json + ``` + +2. Save the service ID from the response: + ```bash + # Extract service_id from the JSON response + export SERVICE_ID="extracted-service-id-from-response" + ``` + +The API returns HTTP 202 (Accepted) for service creation requests, indicating the operation is asynchronous. + +### Monitor service creation progress + +1. Check service status periodically: + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" + ``` + +2. Wait for status to change from `CONFIGURING` to `READY`: + - `QUEUED`: Service creation request is queued + - `CONFIGURING`: Service is being provisioned + - `READY`: Service is available for use + - `UNSTABLE`: Service encountered issues during creation + +Service creation typically completes within 5-10 minutes depending on the configuration. + +## Security best practices + +Follow these security guidelines when working with the TigerData Cloud API: + +### Credential management +- Store API credentials as environment variables, not in code +- Use credential rotation policies for production environments +- Limit credential scope to minimum required permissions +- Never commit credentials to version control systems + +### Network security +- Use HTTPS endpoints exclusively for API communication +- Implement proper certificate validation in your HTTP clients +- Consider IP allowlisting for production API access +- Monitor API access logs for suspicious activity + +### Access control +- Create dedicated service accounts for automated API access +- Use principle of least privilege for API key permissions +- Regularly audit and review API access patterns +- Implement proper session management for interactive applications + +### Data protection +- Encrypt sensitive data before API transmission when applicable +- Use secure storage for service connection strings and passwords +- Implement proper backup and recovery procedures for created services +- Follow data residency requirements for your region + +## Alternative implementation using API explorer + +The TigerData Cloud project includes a command-line API explorer tool that simplifies API interactions: + +### Using the API explorer + +1. Navigate to the API explorer directory: + ```bash + cd api_explorer + ``` + +2. Configure the environment interactively: + ```bash + go run . config setup + ``` + +3. Test the connection: + ```bash + go run . health + ``` + +4. Create a service using the simplified command: + ```bash + go run . service create + ``` + +The API explorer automatically handles authentication, request formatting, and response parsing, making it ideal for development and testing workflows. + +Your TigerData Cloud API is now configured securely, and you have successfully created your first database service. The service provides a managed TimescaleDB instance with the specified resources and configuration. \ No newline at end of file From a48e482ccf516fce6a66bef4c2630fa320a0a6f1 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 25 Aug 2025 09:57:36 +0200 Subject: [PATCH 02/10] chore: first draft of the REST API docs --- api/api-reference.md | 11 +- api/page-index/page-index.js | 6 + getting-started/get-started-devops-as-code.md | 307 ++++++++---------- getting-started/page-index/page-index.js | 5 + 4 files changed, 159 insertions(+), 170 deletions(-) diff --git a/api/api-reference.md b/api/api-reference.md index 952a21e838..e100eb85a0 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -1,6 +1,13 @@ -# TigerData Cloud API Reference +--- +title: Tiger Cloud API reference +excerpt: A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. +tags: [REST] +products: [cloud] +--- -A comprehensive RESTful API for managing TigerData Cloud Platform resources including VPCs, services, and read replicas. +# Tiger Cloud API reference + +A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. ## Overview diff --git a/api/page-index/page-index.js b/api/page-index/page-index.js index 049f79920a..f2c4411d9f 100644 --- a/api/page-index/page-index.js +++ b/api/page-index/page-index.js @@ -587,6 +587,12 @@ module.exports = [ description: "An overview of what different tags represent in the API section of TigerData Documentation.", }, + { + title: "Tiger Cloud REST API", + href: "api-reference", + description: + "A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas.", + }, { title: "Compression (Old API, replaced by Hypercore)", href: "compression", diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index df696d561a..6ddc27b4aa 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -1,6 +1,6 @@ --- -title: "Set up TigerData Cloud API and create your first service" -excerpt: "Configure secure authentication and create a new database service using the TigerData Cloud API" +title: "Set up Tiger Cloud REST API and create your first service" +excerpt: "Configure secure authentication and create a new database service using the Tiger Cloud REST API" keywords: - authentication - service creation @@ -13,111 +13,106 @@ tags: - authentication --- -# Set up TigerData Cloud API and create your first service +import IntegrationPrereqs from "versionContent/_partials/_integration-prereqs.mdx"; -Set up secure authentication for the TigerData Cloud API and create your first database service. This procedure covers credential configuration, security best practices, and service creation using the RESTful API. +# Get started with Tiger Cloud REST API -## Prerequisites - -Complete the following prerequisites before setting up the API: - -- Valid TigerData Cloud account with API access -- Project ID from your TigerData Cloud console -- API access key and secret key with appropriate permissions -- Command-line tool (cURL, HTTPie, or programming language with HTTP client) -- OpenAPI specification file for reference -- Network connectivity to TigerData Cloud API endpoints - -## Configure secure authentication - -The TigerData Cloud API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include proper authentication headers. - -### Set up API credentials - -1. Obtain your API credentials from the TigerData Cloud console: - - Access key: Your unique API identifier - - Secret key: Your private authentication token - - Project ID: The identifier for your TigerData project - -2. Store credentials securely using environment variables: - ```bash - export TIGERDATA_ACCESS_KEY="your-access-key" - export TIGERDATA_SECRET_KEY="your-secret-key" - export TIGERDATA_PROJECT_ID="your-project-id" - ``` - -3. Verify credential format: - - Access key format: Alphanumeric string (typically 10-20 characters) - - Secret key format: Base64-encoded string (typically 40-60 characters) - - Project ID format: Alphanumeric string starting with project prefix - -### Configure API endpoint - -Set the appropriate API base URL for your environment: +[Tiger Cloud REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read +replicas. -```bash -# Development environment (recommended for testing) -export API_BASE_URL="https://console.dev.timescale.com/public/api/v1" +This page shows you how to set up secure authentication for the TigerData Cloud REST API and create your first service. -# Production environment -export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" - -# Local development (if running local server) -export API_BASE_URL="http://localhost:8080/public/api/v1" -``` - -## Test API connection - -Verify your authentication setup and API connectivity before creating resources. - -### Perform health check - -Test the API connection using a simple health check request: - -```bash -curl -X GET "${API_BASE_URL}/healthcheck" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" -``` +## Prerequisites -Expected response: -```json -{ - "status": "healthy", - "timestamp": "2024-01-15T10:30:00Z" -} -``` + -### Validate authentication +- An [API access key and secret key][rest-api-credentials] +- A Command-line tool for REST calls +- Network connectivity to Tiger Cloud REST API endpoints -Test authentication by listing existing services: +## Configure secure authentication -```bash -curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" -``` +Tiger Cloud REST API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include +proper authentication headers. + + + +1. **Set up API credentials** + + 1. Obtain your API credentials from the TigerData Cloud console: + - Access key: Your unique API identifier + - Secret key: Your private authentication token + - Project ID: The identifier for your TigerData project + + 2. Store credentials securely using environment variables: + ```bash + export TIGERDATA_ACCESS_KEY="your-access-key" + export TIGERDATA_SECRET_KEY="your-secret-key" + export TIGERDATA_PROJECT_ID="your-project-id" + ``` + + 3. Verify credential format: + - Access key format: Alphanumeric string (typically 10-20 characters) + - Secret key format: Base64-encoded string (typically 40-60 characters) + - Project ID format: Alphanumeric string starting with project prefix + +1. **Configure API endpoint** + + Set the appropriate API base URL for your environment: + + ```bash + # Development environment (recommended for testing) + export API_BASE_URL="https://console.dev.timescale.com/public/api/v1" + + # Production environment + export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" + + # Local development (if running local server) + export API_BASE_URL="http://localhost:8080/public/api/v1" + ``` + +1. **Test API connection** + + Verify your authentication setup and API connectivity before creating resources. + +1. **Perform health check** + + Test the API connection using a simple health check request: + + ```bash + curl -X GET "${API_BASE_URL}/healthcheck" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" + ``` + + Expected response: + ```json + { + "status": "healthy", + "timestamp": "2024-01-15T10:30:00Z" + } + ``` + +1. **Validate authentication** + + Test authentication by listing existing services: + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" + ``` + + Successful authentication returns a JSON array of services (may be empty for new projects). ## Create your first service -Create a new database service using the TigerData Cloud API with secure configuration. - -### Prepare service configuration +Create a new database service using the Tiger Cloud REST API with secure configuration. -1. Define the service creation payload in JSON format: - ```json - { - "name": "my-first-service", - "service_type": "TIMESCALEDB", - "region_code": "google-europe-west1", - "replica_count": 1, - "cpu_millis": 1000, - "memory_gbs": 4 - } - ``` + -2. Save the configuration to a file for reuse: +1. **Define the service creation payload in a JSON file** ```bash cat > service-config.json << 'EOF' { @@ -131,95 +126,71 @@ Create a new database service using the TigerData Cloud API with secure configur EOF ``` -### Submit service creation request - -1. Create the service using the POST endpoint: - ```bash - curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d @service-config.json - ``` - -2. Save the service ID from the response: - ```bash - # Extract service_id from the JSON response - export SERVICE_ID="extracted-service-id-from-response" - ``` +1. **Submit service creation request** -The API returns HTTP 202 (Accepted) for service creation requests, indicating the operation is asynchronous. + 1. Create the service using the POST endpoint: + ```bash + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d @service-config.json + ``` -### Monitor service creation progress + 2. Save the service ID from the response: + ```bash + # Extract service_id from the JSON response + export SERVICE_ID="extracted-service-id-from-response" + ``` -1. Check service status periodically: - ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" - ``` + The API returns HTTP 202 (Accepted) for service creation requests, indicating the operation is asynchronous. -2. Wait for status to change from `CONFIGURING` to `READY`: - - `QUEUED`: Service creation request is queued - - `CONFIGURING`: Service is being provisioned - - `READY`: Service is available for use - - `UNSTABLE`: Service encountered issues during creation +1. **Monitor service creation progress** -Service creation typically completes within 5-10 minutes depending on the configuration. + 1. Check service status periodically: + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" + ``` -## Security best practices + 2. Wait for status to change from `CONFIGURING` to `READY`: + - `QUEUED`: Service creation request is queued + - `CONFIGURING`: Service is being provisioned + - `READY`: Service is available for use + - `UNSTABLE`: Service encountered issues during creation -Follow these security guidelines when working with the TigerData Cloud API: + Service creation typically completes within 5-10 minutes depending on the configuration. -### Credential management -- Store API credentials as environment variables, not in code -- Use credential rotation policies for production environments -- Limit credential scope to minimum required permissions -- Never commit credentials to version control systems + -### Network security -- Use HTTPS endpoints exclusively for API communication -- Implement proper certificate validation in your HTTP clients -- Consider IP allowlisting for production API access -- Monitor API access logs for suspicious activity - -### Access control -- Create dedicated service accounts for automated API access -- Use principle of least privilege for API key permissions -- Regularly audit and review API access patterns -- Implement proper session management for interactive applications +## Security best practices -### Data protection -- Encrypt sensitive data before API transmission when applicable -- Use secure storage for service connection strings and passwords -- Implement proper backup and recovery procedures for created services -- Follow data residency requirements for your region +Follow these security guidelines when working with the Tiger Cloud REST API: -## Alternative implementation using API explorer +- **Credential management** + - Store API credentials as environment variables, not in code + - Use credential rotation policies for production environments + - Limit credential scope to minimum required permissions + - Never commit credentials to version control systems -The TigerData Cloud project includes a command-line API explorer tool that simplifies API interactions: +- **Network security** + - Use HTTPS endpoints exclusively for API communication + - Implement proper certificate validation in your HTTP clients + - Consider IP allowlisting for production API access + - Monitor API access logs for suspicious activity -### Using the API explorer +- **Access control** + - Create dedicated service accounts for automated API access + - Use principle of least privilege for API key permissions + - Regularly audit and review API access patterns + - Implement proper session management for interactive applications -1. Navigate to the API explorer directory: - ```bash - cd api_explorer - ``` - -2. Configure the environment interactively: - ```bash - go run . config setup - ``` - -3. Test the connection: - ```bash - go run . health - ``` - -4. Create a service using the simplified command: - ```bash - go run . service create - ``` +- **Data protection** + - Encrypt sensitive data before API transmission when applicable + - Use secure storage for service connection strings and passwords + - Implement proper backup and recovery procedures for created services + - Follow data residency requirements for your region -The API explorer automatically handles authentication, request formatting, and response parsing, making it ideal for development and testing workflows. -Your TigerData Cloud API is now configured securely, and you have successfully created your first database service. The service provides a managed TimescaleDB instance with the specified resources and configuration. \ No newline at end of file +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings \ No newline at end of file diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index 08356efc97..8c52c4857a 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -22,6 +22,11 @@ module.exports = [ href: "services", excerpt: "Create a Tiger Cloud service and connect to it", }, + { + title: "Get started with Tiger Cloud REST API", + href: "get-started-devops-as-code", + excerpt: "Set up secure authentication for the TigerData Cloud REST API and create your first service", + }, { title: "Run your queries from Tiger Cloud Console", href: "run-queries-from-console", From 496846a8b19ceb758b6a0ef5cda3e59034b0c8c0 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Wed, 27 Aug 2025 14:17:44 +0200 Subject: [PATCH 03/10] chore: update and test. --- _partials/_prereqs-cloud-account-only.md | 5 ++ getting-started/get-started-devops-as-code.md | 51 +++++++------------ integrations/find-connection-details.md | 30 ++++++++++- 3 files changed, 52 insertions(+), 34 deletions(-) create mode 100644 _partials/_prereqs-cloud-account-only.md diff --git a/_partials/_prereqs-cloud-account-only.md b/_partials/_prereqs-cloud-account-only.md new file mode 100644 index 0000000000..9d31734690 --- /dev/null +++ b/_partials/_prereqs-cloud-account-only.md @@ -0,0 +1,5 @@ +To follow the steps on this page: + +* Create a target [$CLOUD_LONG account][create-account]. + +[create-account]: /getting-started/:currentVersion:/services/#create-a-tiger-cloud-account \ No newline at end of file diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index 6ddc27b4aa..f453883df7 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -13,69 +13,52 @@ tags: - authentication --- -import IntegrationPrereqs from "versionContent/_partials/_integration-prereqs.mdx"; +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; # Get started with Tiger Cloud REST API -[Tiger Cloud REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read +[$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read replicas. This page shows you how to set up secure authentication for the TigerData Cloud REST API and create your first service. ## Prerequisites - - -- An [API access key and secret key][rest-api-credentials] + - A Command-line tool for REST calls - Network connectivity to Tiger Cloud REST API endpoints ## Configure secure authentication -Tiger Cloud REST API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include +$CLOUD_LONG REST API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include proper authentication headers. 1. **Set up API credentials** - 1. Obtain your API credentials from the TigerData Cloud console: - - Access key: Your unique API identifier - - Secret key: Your private authentication token - - Project ID: The identifier for your TigerData project - - 2. Store credentials securely using environment variables: + 1. In $CONSOLE [copy your project ID][get-project-id] and store it securely using an environment variable: + ```bash - export TIGERDATA_ACCESS_KEY="your-access-key" - export TIGERDATA_SECRET_KEY="your-secret-key" export TIGERDATA_PROJECT_ID="your-project-id" ``` - 3. Verify credential format: - - Access key format: Alphanumeric string (typically 10-20 characters) - - Secret key format: Base64-encoded string (typically 40-60 characters) - - Project ID format: Alphanumeric string starting with project prefix + 1. In $CONSOLE [create your client credentials][create-client-credentials] and store them securely using environment variables: + + ```bash + export TIGERDATA_ACCESS_KEY="Public key" + export TIGERDATA_SECRET_KEY="Secret key" + ``` 1. **Configure API endpoint** - Set the appropriate API base URL for your environment: + Set the API base URL for your environment: ```bash - # Development environment (recommended for testing) - export API_BASE_URL="https://console.dev.timescale.com/public/api/v1" - - # Production environment export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" - - # Local development (if running local server) - export API_BASE_URL="http://localhost:8080/public/api/v1" ``` -1. **Test API connection** - - Verify your authentication setup and API connectivity before creating resources. - -1. **Perform health check** +1. **Perform health check and test your connection to $CLOUD_LONG REST API** Test the API connection using a simple health check request: @@ -118,7 +101,7 @@ Create a new database service using the Tiger Cloud REST API with secure configu { "name": "my-first-service", "service_type": "TIMESCALEDB", - "region_code": "google-europe-west1", + "region_code": "us-east-1", "replica_count": 1, "cpu_millis": 1000, "memory_gbs": 4 @@ -193,4 +176,6 @@ Follow these security guidelines when working with the Tiger Cloud REST API: [rest-api-reference]: /api/:currentVersion:/api-reference/ -[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings \ No newline at end of file +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials \ No newline at end of file diff --git a/integrations/find-connection-details.md b/integrations/find-connection-details.md index 7df2ce0722..2f46815a00 100644 --- a/integrations/find-connection-details.md +++ b/integrations/find-connection-details.md @@ -41,7 +41,7 @@ To retrieve the connection details for your $CLOUD_LONG project and $SERVICE_LON -1. **Retreive your project ID**: +1. **Retrieve your project ID**: In [$CONSOLE][console-services], click your project name in the upper left corner, then click `Copy` next to the project ID. ![Retrive the project id in $CONSOLE](https://assets.timescale.com/docs/images/tiger-cloud-console/tiger-cloud-console-project-id.png) @@ -53,6 +53,31 @@ To retrieve the connection details for your $CLOUD_LONG project and $SERVICE_LON +## Create client credentials + +You use client credentials to obtain access tokens outside of the user context. + +To retrieve the connection details for your $CLOUD_LONG project for programmatic usage +such as Terraform or the [$CLOUD_LONG REST API][rest-api-reference]: + + + +1. **Open the settings for your project**: + + In [$CONSOLE][console-services], click your project name in the upper left corner, then click `Project settings`. + +1. **Create client credentials**: + + 1. Click `Create credentials`, then copy `Public key` and `Secret key` locally. + + ![Retrive the service id in $CONSOLE](https://assets.timescale.com/docs/images/tiger-cloud-console/tiger-cloud-console-client-credentials.png) + + This is the only time you see the `Secret key`. After this, only the `Public key` is visible in this page. + + 1. Click `Done`. + + + @@ -73,3 +98,6 @@ In the `Services` page of the $MST_CONSOLE_LONG, click the service you want to c [console-services]: https://console.cloud.timescale.com/dashboard/services [postgres-config]: https://www.postgresql.org/docs/current/runtime-config-file-locations.html +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials \ No newline at end of file From 0aa622e534a41a726fb5bed81700fc877249ced8 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Wed, 27 Aug 2025 14:24:18 +0200 Subject: [PATCH 04/10] chore: update and test. --- getting-started/get-started-devops-as-code.md | 12 +++++++----- getting-started/page-index/page-index.js | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index f453883df7..aa85e6a578 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -1,5 +1,5 @@ --- -title: "Set up Tiger Cloud REST API and create your first service" +title: "DevOps with Tiger Cloud REST API" excerpt: "Configure secure authentication and create a new database service using the Tiger Cloud REST API" keywords: - authentication @@ -15,7 +15,7 @@ tags: import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; -# Get started with Tiger Cloud REST API +# DevOps with Tiger Cloud REST API [$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read replicas. @@ -25,8 +25,9 @@ This page shows you how to set up secure authentication for the TigerData Cloud ## Prerequisites -- A Command-line tool for REST calls -- Network connectivity to Tiger Cloud REST API endpoints + +* Install [curl][curl]. + ## Configure secure authentication @@ -178,4 +179,5 @@ Follow these security guidelines when working with the Tiger Cloud REST API: [rest-api-reference]: /api/:currentVersion:/api-reference/ [rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings [get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id -[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials \ No newline at end of file +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ \ No newline at end of file diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index 8c52c4857a..a8681649f7 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -23,7 +23,7 @@ module.exports = [ excerpt: "Create a Tiger Cloud service and connect to it", }, { - title: "Get started with Tiger Cloud REST API", + title: "DevOps with Tiger Cloud REST API", href: "get-started-devops-as-code", excerpt: "Set up secure authentication for the TigerData Cloud REST API and create your first service", }, From 20a0a27ba0b7506fce205405fce4067d99c850e9 Mon Sep 17 00:00:00 2001 From: josesahad Date: Fri, 5 Sep 2025 11:53:56 +0200 Subject: [PATCH 05/10] Fix spec. Better examples and documentation --- api/api-reference.md | 684 +++++++++++++++++++++---------------------- 1 file changed, 341 insertions(+), 343 deletions(-) diff --git a/api/api-reference.md b/api/api-reference.md index e100eb85a0..0cfc44914e 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -12,9 +12,7 @@ A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, s ## Overview **API Version:** 1.0.0 -**Base URL:** `https://api.tigerdata.com/public/v1` -**Development URL:** `https://console.dev.timescale.com/public/api/v1` -**Local Development URL:** `http://localhost:8080/public/api/v1` +**Base URL:** `https://console.cloud.timescale.com/public/api/v1` ## Authentication @@ -28,214 +26,10 @@ Authorization: Basic ### Example ```bash # Using cURL -curl -X GET "https://api.tigerdata.com/public/v1/projects/{project_id}/services" \ +curl -X GET "https://console.cloud.timescale.com/public/api/v1/projects/{project_id}/services" \ -H "Authorization: Basic $(echo -n 'your_access_key:your_secret_key' | base64)" ``` -### Error Responses -- **401 Unauthorized:** Invalid or missing credentials -- **403 Forbidden:** Insufficient permissions - -## Common Parameters - -### Path Parameters -- `project_id` (string): The unique identifier of the project (e.g., "rp1pz7uyae") -- `service_id` (string): The unique identifier of the service (e.g., "d1k5vk7hf2") -- `vpc_id` (string): The unique identifier of the VPC (e.g., "1234567890") -- `replica_set_id` (string): The unique identifier of the read replica set (e.g., "alb8jicdpr") -- `peering_id` (string): The unique identifier of the VPC peering connection (e.g., "1234567890") - -## VPC Management - -Virtual Private Clouds (VPCs) provide network isolation for your TigerData services. - -### List All VPCs - -```http -GET /projects/{project_id}/vpcs -``` - -Lists all Virtual Private Clouds in a project. - -**Response:** `200 OK` -```json -[ - { - "id": "1234567890", - "name": "my-production-vpc", - "cidr": "10.0.0.0/16", - "region_code": "google-europe-west1" - } -] -``` - -### Create a VPC - -```http -POST /projects/{project_id}/vpcs -``` - -Creates a new Virtual Private Cloud. - -**Request Body:** -```json -{ - "name": "my-production-vpc", - "cidr": "10.0.0.0/16", - "region_code": "google-europe-west1" -} -``` - -**Response:** `201 Created` -```json -{ - "id": "1234567890", - "name": "my-production-vpc", - "cidr": "10.0.0.0/16", - "region_code": "google-europe-west1" -} -``` - -**Error Responses:** -- `400 Bad Request`: Invalid request parameters - -### Get a VPC - -```http -GET /projects/{project_id}/vpcs/{vpc_id} -``` - -Retrieves details of a specific VPC. - -**Response:** `200 OK` -```json -{ - "id": "1234567890", - "name": "my-production-vpc", - "cidr": "10.0.0.0/16", - "region_code": "google-europe-west1" -} -``` - -**Error Responses:** -- `404 Not Found`: VPC not found - -### Rename a VPC - -```http -POST /projects/{project_id}/vpcs/{vpc_id}/rename -``` - -Updates the name of a specific VPC. - -**Request Body:** -```json -{ - "name": "my-renamed-vpc" -} -``` - -**Response:** `200 OK` -```json -{ - "id": "1234567890", - "name": "my-renamed-vpc", - "cidr": "10.0.0.0/16", - "region_code": "google-europe-west1" -} -``` - -**Error Responses:** -- `400 Bad Request`: Invalid request parameters -- `404 Not Found`: VPC not found - -### Delete a VPC - -```http -DELETE /projects/{project_id}/vpcs/{vpc_id} -``` - -Deletes a specific VPC. - -**Response:** `204 No Content` - -**Error Responses:** -- `404 Not Found`: VPC not found - -## VPC Peering - -Manage peering connections between VPCs across different accounts and regions. - -### List VPC Peerings - -```http -GET /projects/{project_id}/vpcs/{vpc_id}/peerings -``` - -Retrieves all VPC peering connections for a given VPC. - -**Response:** `200 OK` -```json -[ - { - "id": "1234567890", - "peer_account_id": "acc-12345", - "peer_region_code": "aws-us-east-1", - "peer_vpc_id": "1234567890", - "provisioned_id": "1234567890", - "status": "active", - "error_message": null - } -] -``` - -### Create VPC Peering - -```http -POST /projects/{project_id}/vpcs/{vpc_id}/peerings -``` - -Creates a new VPC peering connection. - -**Request Body:** -```json -{ - "peer_account_id": "acc-12345", - "peer_region_code": "aws-us-east-1", - "peer_vpc_id": "1234567890" -} -``` - -**Response:** `201 Created` -```json -{ - "id": "1234567890", - "peer_account_id": "acc-12345", - "peer_region_code": "aws-us-east-1", - "peer_vpc_id": "1234567890", - "provisioned_id": "1234567890", - "status": "pending" -} -``` - -### Get VPC Peering - -```http -GET /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} -``` - -Retrieves details of a specific VPC peering connection. - -### Delete VPC Peering - -```http -DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} -``` - -Deletes a specific VPC peering connection. - -**Response:** `204 No Content` - ## Service Management Manage database services including TimescaleDB, PostgreSQL, and Vector databases. @@ -252,14 +46,13 @@ Retrieves all services within a project. ```json [ { - "service_id": "d1k5vk7hf2", - "project_id": "rp1pz7uyae", + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", "name": "my-production-db", - "region_code": "google-europe-west1", + "region_code": "eu-central-1", "service_type": "TIMESCALEDB", "status": "READY", "created": "2024-01-15T10:30:00Z", - "initial_password": "a-very-secure-initial-password", "paused": false, "resources": [ { @@ -290,10 +83,9 @@ Creates a new database service. This is an asynchronous operation. **Request Body:** ```json { - "name": "my-production-db", + "name": "test-2", "service_type": "TIMESCALEDB", - "region_code": "google-europe-west1", - "replica_count": 1, + "region_code": "eu-central-1", "cpu_millis": 1000, "memory_gbs": 4 } @@ -302,14 +94,32 @@ Creates a new database service. This is an asynchronous operation. **Response:** `202 Accepted` ```json { - "service_id": "d1k5vk7hf2", - "project_id": "rp1pz7uyae", - "name": "my-production-db", - "region_code": "google-europe-west1", + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "test-2", + "region_code": "eu-central-1", "service_type": "TIMESCALEDB", - "status": "QUEUED", - "created": "2024-01-15T10:30:00Z", - "initial_password": "a-very-secure-initial-password" + "created": "2025-09-04T20:46:46.265680278Z", + "paused": false, + "status": "READY", + "resources": [ + { + "id": "100927", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } + } + ], + "metadata": { + "environment": "PROD" + }, + "endpoint": { + "host": "p7zm8wqqii.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 35482 + }, + "initial_password": "oamv8ch9t4ar2j8g" } ``` @@ -318,9 +128,6 @@ Creates a new database service. This is an asynchronous operation. - `POSTGRES`: PostgreSQL service - `VECTOR`: Vector database service -**Error Responses:** -- `400 Bad Request`: Invalid service configuration - ### Get a Service ```http @@ -332,36 +139,30 @@ Retrieves details of a specific service. **Response:** `200 OK` ```json { - "service_id": "d1k5vk7hf2", - "project_id": "rp1pz7uyae", - "name": "my-production-db", - "region_code": "google-europe-west1", + "service_id": "p7zm9wqqii", + "project_id": "jz22xtzemv", + "name": "test-2", + "region_code": "eu-central-1", "service_type": "TIMESCALEDB", - "status": "READY", - "created": "2024-01-15T10:30:00Z", + "created": "2025-09-04T20:46:46.26568Z", "paused": false, + "status": "READY", "resources": [ - { - "id": "resource-1", - "spec": { - "cpu_millis": 1000, - "memory_gbs": 4, - "volume_type": "gp2" + { + "id": "100927", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } } - } ], "metadata": { - "environment": "PROD" + "environment": "DEV" }, "endpoint": { - "host": "my-service.com", - "port": 5432 - }, - "connection_pooler": { - "endpoint": { - "host": "pooler.my-service.com", - "port": 5432 - } + "host": "p7zm8wqqii.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 35482 } } ``` @@ -389,9 +190,6 @@ Deletes a specific service. This is an asynchronous operation. **Response:** `202 Accepted` -**Error Responses:** -- `404 Not Found`: Service not found - ### Resize a Service ```http @@ -449,7 +247,7 @@ Sets the environment type for the service. **Response:** `200 OK` ```json { - "message": "Action completed successfully." + "message": "Environment set successfully" } ``` @@ -464,8 +262,7 @@ Changes the HA configuration for a service. This is an asynchronous operation. **Request Body:** ```json { - "sync_replica_count": 1, - "replica_count": 2 + "replica_count": 1 } ``` @@ -484,7 +281,7 @@ Activates the connection pooler for a service. **Response:** `200 OK` ```json { - "message": "Action completed successfully." + "message": "Connection pooler enabled successfully" } ``` @@ -497,45 +294,10 @@ POST /projects/{project_id}/services/{service_id}/disablePooler Deactivates the connection pooler for a service. **Response:** `200 OK` - -### Service VPC Operations - -#### Attach Service to VPC - -```http -POST /projects/{project_id}/services/{service_id}/attachToVPC -``` - -Associates a service with a VPC. - -**Request Body:** ```json { - "vpc_id": "1234567890" + "message": "Connection pooler disabled successfully" } -``` - -**Response:** `202 Accepted` - -**Error Responses:** -- `409 Conflict`: Service already attached to a VPC - -#### Detach Service from VPC - -```http -POST /projects/{project_id}/services/{service_id}/detachFromVPC -``` - -Disassociates a service from its VPC. - -**Request Body:** -```json -{ - "vpc_id": "1234567890" -} -``` - -**Response:** `202 Accepted` ### Fork a Service @@ -548,27 +310,46 @@ Creates a new, independent service by taking a snapshot of an existing one. **Request Body:** ```json { - "name": "forked-customer-db" + "name": "fork-test2", + "region_code": "eu-central-1", + "cpu_millis": 1000, + "memory_gbs": 4 } ``` **Response:** `202 Accepted` ```json { - "service_id": "new-service-id", - "name": "forked-customer-db", - "forked_from": { - "project_id": "rp1pz7uyae", - "service_id": "d1k5vk7hf2", - "is_standby": false - }, - "status": "CONFIGURING" + "service_id": "otewd3pem2", + "project_id": "jz22xtzemv", + "name": "fork-test2", + "region_code": "eu-central-1", + "service_type": "TIMESCALEDB", + "created": "2025-09-04T20:54:09.53380732Z", + "paused": false, + "status": "READY", + "resources": [ + { + "id": "100929", + "spec": { + "cpu_millis": 1000, + "memory_gbs": 4, + "volume_type": "" + } + } + ], + "forked_from": { + "project_id": "jz22xtzemv", + "service_id": "p7zm9wqqii", + "is_standby": false + }, + "initial_password": "ph33bl5juuri5gem" } ``` ## Read Replica Sets -Manage read replicas for improved read performance and geographical distribution. +Manage read replicas for improved read performance. ### List Read Replica Sets @@ -582,18 +363,18 @@ Retrieves all read replica sets associated with a primary service. ```json [ { - "id": "alb8jicdpr", - "name": "reporting-replica-1", + "id": "dsldm715t2", + "name": "replica-set-test", "status": "active", - "nodes": 2, - "cpu_millis": 250, - "memory_gbs": 0.5, + "nodes": 1, + "cpu_millis": 500, + "memory_gbs": 2, "metadata": { "environment": "PROD" }, "endpoint": { - "host": "replica.my-service.com", - "port": 5432 + "host": "jz22xtzemv.dsldm715t2.tsdb.cloud.timescale.com", + "port": 39680 } } ] @@ -617,22 +398,22 @@ Creates a new read replica set. This is an asynchronous operation. **Request Body:** ```json { - "name": "my-reporting-replica", - "nodes": 2, - "cpu_millis": 250, - "memory_gbs": 0.5 + "name": "replica-set-test2", + "cpu_millis": 1000, + "memory_gbs": 4, + "nodes": 1 } ``` **Response:** `202 Accepted` ```json { - "id": "alb8jicdpr", - "name": "my-reporting-replica", - "status": "creating", - "nodes": 2, - "cpu_millis": 250, - "memory_gbs": 0.5 + "id": "dsldm715t2", + "name": "replica-set-test2", + "status": "active", + "nodes": 1, + "cpu_millis": 1000, + "memory_gbs": 4 } ``` @@ -652,22 +433,27 @@ Deletes a specific read replica set. This is an asynchronous operation. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/resize ``` -Changes resource allocation for a read replica set. +Changes resource allocation for a read replica set. This operation is async. **Request Body:** ```json { "cpu_millis": 500, - "memory_gbs": 1.0, - "nodes": 3 + "memory_gbs": 2, + "nodes": 2 } ``` **Response:** `202 Accepted` +```json +{ + "message": "Replica set resize request accepted" +} +``` -### Read Replica Connection Pooler +### Read Replica Set Connection Pooler -#### Enable Replica Pooler +#### Enable Replica Set Pooler ```http POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler @@ -676,8 +462,13 @@ POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/e Activates the connection pooler for a read replica set. **Response:** `200 OK` +```json +{ + "message": "Connection pooler enabled successfully" +} +``` -#### Disable Replica Pooler +#### Disable Replica Set Pooler ```http POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler @@ -686,8 +477,13 @@ POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/d Deactivates the connection pooler for a read replica set. **Response:** `200 OK` +```json +{ + "message": "Connection pooler disabled successfully" +} +``` -### Set Replica Environment +### Set Replica Set Environment ```http POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment @@ -703,6 +499,225 @@ Sets the environment type for a read replica set. ``` **Response:** `200 OK` +```json +{ + "message": "Environment set successfully" +} +``` + +## VPC Management + +Virtual Private Clouds (VPCs) provide network isolation for your TigerData services. + +### List All VPCs + +```http +GET /projects/{project_id}/vpcs +``` + +Lists all Virtual Private Clouds in a project. + +**Response:** `200 OK` +```json +[ + { + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" + } +] +``` + +### Create a VPC + +```http +POST /projects/{project_id}/vpcs +``` + +Creates a new VPC. + +**Request Body:** +```json +{ + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +### Get a VPC + +```http +GET /projects/{project_id}/vpcs/{vpc_id} +``` + +Retrieves details of a specific VPC. + +**Response:** `200 OK` +```json +{ + "id": "1234567890", + "name": "my-production-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +### Rename a VPC + +```http +POST /projects/{project_id}/vpcs/{vpc_id}/rename +``` + +Updates the name of a specific VPC. + +**Request Body:** +```json +{ + "name": "my-renamed-vpc" +} +``` + +**Response:** `200 OK` +```json +{ + "id": "1234567890", + "name": "my-renamed-vpc", + "cidr": "10.0.0.0/16", + "region_code": "eu-central-1" +} +``` + +### Delete a VPC + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id} +``` + +Deletes a specific VPC. + +**Response:** `204 No Content` + +## VPC Peering + +Manage peering connections between VPCs across different accounts and regions. + +### List VPC Peerings + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings +``` + +Retrieves all VPC peering connections for a given VPC. + +**Response:** `200 OK` +```json +[ + { + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "eu-central-1", + "peer_vpc_id": "1234567890", + "provisioned_id": "1234567890", + "status": "active", + "error_message": null + } +] +``` + +### Create VPC Peering + +```http +POST /projects/{project_id}/vpcs/{vpc_id}/peerings +``` + +Creates a new VPC peering connection. + +**Request Body:** +```json +{ + "peer_account_id": "acc-12345", + "peer_region_code": "eu-central-1", + "peer_vpc_id": "1234567890" +} +``` + +**Response:** `201 Created` +```json +{ + "id": "1234567890", + "peer_account_id": "acc-12345", + "peer_region_code": "eu-central-1", + "peer_vpc_id": "1234567890", + "provisioned_id": "1234567890", + "status": "pending" +} +``` + +### Get VPC Peering + +```http +GET /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Retrieves details of a specific VPC peering connection. + +### Delete VPC Peering + +```http +DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} +``` + +Deletes a specific VPC peering connection. + +**Response:** `204 No Content` + +## Service VPC Operations + +### Attach Service to VPC + +```http +POST /projects/{project_id}/services/{service_id}/attachToVPC +``` + +Associates a service with a VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` + +### Detach Service from VPC + +```http +POST /projects/{project_id}/services/{service_id}/detachFromVPC +``` + +Disassociates a service from its VPC. + +**Request Body:** +```json +{ + "vpc_id": "1234567890" +} +``` + +**Response:** `202 Accepted` ## Data Models @@ -774,8 +789,8 @@ Sets the environment type for a read replica set. "name": "string", "status": "creating|active|resizing|deleting|error", "nodes": 2, - "cpu_millis": 250, - "memory_gbs": 0.5, + "cpu_millis": 1000, + "memory_gbs": 4, "metadata": { "environment": "PROD|DEV" }, @@ -819,20 +834,3 @@ The API uses standard HTTP status codes and returns error details in JSON format "message": "The service_type field is required" } ``` - -## Rate Limiting - -The API implements rate limiting to ensure fair usage: - -- **Development Environment**: More lenient rate limits for testing -- **Production Environment**: Strict rate limits for stability -- **Local Development**: No rate limits applied - -When rate limits are exceeded, the API returns `429 Too Many Requests` with retry information in the response headers. - -## Support and Contact - -For API support and questions: -- **Support**: [TigerData Support](https://www.tigerdata.com/contact) -- **License**: [Terms of Service](https://www.tigerdata.com/legal/terms) -- **Documentation**: This API reference follows the OpenAPI 3.0.3 specification \ No newline at end of file From 2f12d32ff4fff27c77b0a539a8585de5df75180a Mon Sep 17 00:00:00 2001 From: josesahad Date: Fri, 5 Sep 2025 13:00:57 +0200 Subject: [PATCH 06/10] Fix replica set retrieval docs --- api/api-reference.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/api/api-reference.md b/api/api-reference.md index 0cfc44914e..b6f8db3dc3 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -363,18 +363,24 @@ Retrieves all read replica sets associated with a primary service. ```json [ { - "id": "dsldm715t2", - "name": "replica-set-test", + "id": "l5alxb3s2g", + "name": "replica-set-test2", "status": "active", "nodes": 1, - "cpu_millis": 500, - "memory_gbs": 2, - "metadata": { - "environment": "PROD" - }, + "cpu_millis": 1000, + "memory_gbs": 4, "endpoint": { - "host": "jz22xtzemv.dsldm715t2.tsdb.cloud.timescale.com", - "port": 39680 + "host": "l5alxb3s2g.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 38448 + }, + "connection_pooler": { + "endpoint": { + "host": "l5alxb3s2g.jz4qxtzemv.tsdb.cloud.timescale.com", + "port": 38543 + } + }, + "metadata": { + "environment": "DEV" } } ] From 81b21fcf7ef32815dad1c0e464477d5736ae657b Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 9 Sep 2025 11:21:28 +0100 Subject: [PATCH 07/10] chore: few small updates. --- api/api-reference.md | 79 +++++++++------- getting-started/get-started-devops-as-code.md | 94 ++++++++++--------- 2 files changed, 95 insertions(+), 78 deletions(-) diff --git a/api/api-reference.md b/api/api-reference.md index b6f8db3dc3..7dbea75899 100644 --- a/api/api-reference.md +++ b/api/api-reference.md @@ -1,11 +1,11 @@ --- -title: Tiger Cloud API reference +title: Tiger Cloud REST API reference excerpt: A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. tags: [REST] products: [cloud] --- -# Tiger Cloud API reference +# Tiger Cloud REST API reference A comprehensive RESTful API for managing Tiger Cloud resources including VPCs, services, and read replicas. @@ -32,7 +32,12 @@ curl -X GET "https://console.cloud.timescale.com/public/api/v1/projects/{project ## Service Management -Manage database services including TimescaleDB, PostgreSQL, and Vector databases. +You use this endpoint to create and manage the following Tiger Posgres services: + +- `TIMESCALEDB`: a Tiger Postgres instance optimized for real-time analytics service For time-stamped data like events, + prices, metrics, sensor readings, or any information that changes over time +- `POSTGRES`: a vanilla Postgres instance +- `VECTOR`: a Tiger Postgres instance with vector extensions ### List All Services @@ -40,7 +45,7 @@ Manage database services including TimescaleDB, PostgreSQL, and Vector databases GET /projects/{project_id}/services ``` -Retrieves all services within a project. +Retrieve all services within a project. **Response:** `200 OK` ```json @@ -78,7 +83,7 @@ Retrieves all services within a project. POST /projects/{project_id}/services ``` -Creates a new database service. This is an asynchronous operation. +Create a new Tiger Postgres service. This is an asynchronous operation. **Request Body:** ```json @@ -124,9 +129,10 @@ Creates a new database service. This is an asynchronous operation. ``` **Service Types:** -- `TIMESCALEDB`: TimescaleDB service -- `POSTGRES`: PostgreSQL service -- `VECTOR`: Vector database service +- `TIMESCALEDB`: a Tiger Postgres instance optimized for real-time analytics service For time-stamped data like events, + prices, metrics, sensor readings, or any information that changes over time +- `POSTGRES`: a vanilla Postgres instance +- `VECTOR`: a Tiger Postgres instance with vector extensions ### Get a Service @@ -134,7 +140,7 @@ Creates a new database service. This is an asynchronous operation. GET /projects/{project_id}/services/{service_id} ``` -Retrieves details of a specific service. +Retrieve details of a specific service. **Response:** `200 OK` ```json @@ -186,7 +192,7 @@ Retrieves details of a specific service. DELETE /projects/{project_id}/services/{service_id} ``` -Deletes a specific service. This is an asynchronous operation. +Delete a specific service. This is an asynchronous operation. **Response:** `202 Accepted` @@ -196,7 +202,7 @@ Deletes a specific service. This is an asynchronous operation. POST /projects/{project_id}/services/{service_id}/resize ``` -Changes CPU and memory allocation for a service. +Change CPU and memory allocation for a service. **Request Body:** ```json @@ -214,7 +220,7 @@ Changes CPU and memory allocation for a service. POST /projects/{project_id}/services/{service_id}/updatePassword ``` -Sets a new master password for the service. +Set a new master password for the service. **Request Body:** ```json @@ -231,7 +237,7 @@ Sets a new master password for the service. POST /projects/{project_id}/services/{service_id}/setEnvironment ``` -Sets the environment type for the service. +Set the environment type for the service. **Request Body:** ```json @@ -257,7 +263,7 @@ Sets the environment type for the service. POST /projects/{project_id}/services/{service_id}/setHA ``` -Changes the HA configuration for a service. This is an asynchronous operation. +Change the HA configuration for a service. This is an asynchronous operation. **Request Body:** ```json @@ -276,7 +282,7 @@ Changes the HA configuration for a service. This is an asynchronous operation. POST /projects/{project_id}/services/{service_id}/enablePooler ``` -Activates the connection pooler for a service. +Activate the connection pooler for a service. **Response:** `200 OK` ```json @@ -291,7 +297,7 @@ Activates the connection pooler for a service. POST /projects/{project_id}/services/{service_id}/disablePooler ``` -Deactivates the connection pooler for a service. +Deactivate the connection pooler for a service. **Response:** `200 OK` ```json @@ -305,7 +311,7 @@ Deactivates the connection pooler for a service. POST /projects/{project_id}/services/{service_id}/forkService ``` -Creates a new, independent service by taking a snapshot of an existing one. +Create a new, independent service by taking a snapshot of an existing one. **Request Body:** ```json @@ -357,7 +363,7 @@ Manage read replicas for improved read performance. GET /projects/{project_id}/services/{service_id}/replicaSets ``` -Retrieves all read replica sets associated with a primary service. +Retrieve all read replica sets associated with a primary service. **Response:** `200 OK` ```json @@ -399,7 +405,7 @@ Retrieves all read replica sets associated with a primary service. POST /projects/{project_id}/services/{service_id}/replicaSets ``` -Creates a new read replica set. This is an asynchronous operation. +Create a new read replica set. This is an asynchronous operation. **Request Body:** ```json @@ -429,7 +435,7 @@ Creates a new read replica set. This is an asynchronous operation. DELETE /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id} ``` -Deletes a specific read replica set. This is an asynchronous operation. +Delete a specific read replica set. This is an asynchronous operation. **Response:** `202 Accepted` @@ -439,7 +445,7 @@ Deletes a specific read replica set. This is an asynchronous operation. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/resize ``` -Changes resource allocation for a read replica set. This operation is async. +Change resource allocation for a read replica set. This operation is async. **Request Body:** ```json @@ -465,7 +471,7 @@ Changes resource allocation for a read replica set. This operation is async. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler ``` -Activates the connection pooler for a read replica set. +Activate the connection pooler for a read replica set. **Response:** `200 OK` ```json @@ -480,7 +486,7 @@ Activates the connection pooler for a read replica set. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler ``` -Deactivates the connection pooler for a read replica set. +Deactivate the connection pooler for a read replica set. **Response:** `200 OK` ```json @@ -495,7 +501,7 @@ Deactivates the connection pooler for a read replica set. POST /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment ``` -Sets the environment type for a read replica set. +Set the environment type for a read replica set. **Request Body:** ```json @@ -521,7 +527,7 @@ Virtual Private Clouds (VPCs) provide network isolation for your TigerData servi GET /projects/{project_id}/vpcs ``` -Lists all Virtual Private Clouds in a project. +List all Virtual Private Clouds in a project. **Response:** `200 OK` ```json @@ -541,7 +547,7 @@ Lists all Virtual Private Clouds in a project. POST /projects/{project_id}/vpcs ``` -Creates a new VPC. +Create a new VPC. **Request Body:** ```json @@ -568,7 +574,7 @@ Creates a new VPC. GET /projects/{project_id}/vpcs/{vpc_id} ``` -Retrieves details of a specific VPC. +Retrieve details of a specific VPC. **Response:** `200 OK` ```json @@ -586,7 +592,7 @@ Retrieves details of a specific VPC. POST /projects/{project_id}/vpcs/{vpc_id}/rename ``` -Updates the name of a specific VPC. +Update the name of a specific VPC. **Request Body:** ```json @@ -611,7 +617,7 @@ Updates the name of a specific VPC. DELETE /projects/{project_id}/vpcs/{vpc_id} ``` -Deletes a specific VPC. +Delete a specific VPC. **Response:** `204 No Content` @@ -625,7 +631,7 @@ Manage peering connections between VPCs across different accounts and regions. GET /projects/{project_id}/vpcs/{vpc_id}/peerings ``` -Retrieves all VPC peering connections for a given VPC. +Retrieve all VPC peering connections for a given VPC. **Response:** `200 OK` ```json @@ -648,7 +654,7 @@ Retrieves all VPC peering connections for a given VPC. POST /projects/{project_id}/vpcs/{vpc_id}/peerings ``` -Creates a new VPC peering connection. +Create a new VPC peering connection. **Request Body:** ```json @@ -677,7 +683,7 @@ Creates a new VPC peering connection. GET /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} ``` -Retrieves details of a specific VPC peering connection. +Retrieve details of a specific VPC peering connection. ### Delete VPC Peering @@ -685,7 +691,7 @@ Retrieves details of a specific VPC peering connection. DELETE /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id} ``` -Deletes a specific VPC peering connection. +Delete a specific VPC peering connection. **Response:** `204 No Content` @@ -697,7 +703,7 @@ Deletes a specific VPC peering connection. POST /projects/{project_id}/services/{service_id}/attachToVPC ``` -Associates a service with a VPC. +Associate a service with a VPC. **Request Body:** ```json @@ -714,7 +720,7 @@ Associates a service with a VPC. POST /projects/{project_id}/services/{service_id}/detachFromVPC ``` -Disassociates a service from its VPC. +Disassociate a service from its VPC. **Request Body:** ```json @@ -789,6 +795,7 @@ Disassociates a service from its VPC. ``` ### Read Replica Set Object + ```json { "id": "string", @@ -815,7 +822,7 @@ Disassociates a service from its VPC. ## Error Handling -The API uses standard HTTP status codes and returns error details in JSON format. +Tiger Cloud REST API uses standard HTTP status codes and returns error details in JSON format. ### Error Response Format ```json diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index aa85e6a578..d5b48450a9 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -59,36 +59,32 @@ proper authentication headers. export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" ``` -1. **Perform health check and test your connection to $CLOUD_LONG REST API** - - Test the API connection using a simple health check request: - - ```bash - curl -X GET "${API_BASE_URL}/healthcheck" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" - ``` - - Expected response: - ```json - { - "status": "healthy", - "timestamp": "2024-01-15T10:30:00Z" - } - ``` - -1. **Validate authentication** - - Test authentication by listing existing services: - +1. **Test your authenticated connection to $CLOUD_LONG REST API by listing services** + ```bash curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ -H "Content-Type: application/json" ``` + This call returns something like: + - No services: + ```terminaloutput + []% + ``` + - One or more services: + + ```terminaloutput + [{"service_id":"a59clooxoe","project_id":"c8nmagk8zh","name":"events", + "region_code":"eu-central-1","service_type":"TIMESCALEDB", + "created":"2025-09-09T08:37:15.816443Z","paused":false,"status":"READY", + "resources":[{"id":"101228","spec":{"cpu_millis":500,"memory_gbs":2,"volume_type":""}}], + "metadata":{"environment":"DEV"},"endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com", + "port":12345}}] + ``` + -Successful authentication returns a JSON array of services (may be empty for new projects). ## Create your first service @@ -119,34 +115,48 @@ Create a new database service using the Tiger Cloud REST API with secure configu -H "Content-Type: application/json" \ -d @service-config.json ``` - - 2. Save the service ID from the response: - ```bash - # Extract service_id from the JSON response - export SERVICE_ID="extracted-service-id-from-response" + $CLOUD_LONG creates a production environment for you. You see something like: + ```terminaloutput + { + "service_id":"asdfasdfasdf","project_id":"asdasdfasf","name":"my-first-service", + "region_code":"us-east-1", "service_type":"TIMESCALEDB", + "created":"2025-09-09T09:24:31.997767396Z", "paused":false,"status":"READY", + "resources":[{"id":"101240", + "spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], + "metadata":{"environment":"PROD"}, + "endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com","port":123435}, + "initial_password":"very-secret", + "ha_replicas":{"sync_replica_count":0,"replica_count":1} + } ``` + - The API returns HTTP 202 (Accepted) for service creation requests, indicating the operation is asynchronous. - -1. **Monitor service creation progress** - - 1. Check service status periodically: + 2. Save `service_id` from the response to a variable: ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" + # Extract service_id from the JSON response + export SERVICE_ID="service_id-from-response" ``` - 2. Wait for status to change from `CONFIGURING` to `READY`: - - `QUEUED`: Service creation request is queued - - `CONFIGURING`: Service is being provisioned - - `READY`: Service is available for use - - `UNSTABLE`: Service encountered issues during creation - - Service creation typically completes within 5-10 minutes depending on the configuration. +1. **Change the environment from production to development** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ + -H "Content-Type: application/json" \ + -d '{"environment": "DEV"}' + ``` + You see something like: + ```terminaloutput + { + "message": "Environment set successfully" + } + ``` +And that is it, you are ready to use the [$CLOUD_LONG REST API][rest-api-reference] to manage your +$SERVICE_SHORTs in $CLOUD_LONG. + ## Security best practices Follow these security guidelines when working with the Tiger Cloud REST API: From 39a62ae1a36511ecdc91a736d8da7afba38a764c Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 9 Sep 2025 12:02:59 +0100 Subject: [PATCH 08/10] chore: few small updates. --- getting-started/get-started-devops-as-code.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index d5b48450a9..8df4ac02c7 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -51,9 +51,9 @@ proper authentication headers. export TIGERDATA_SECRET_KEY="Secret key" ``` -1. **Configure API endpoint** +1. **Configure the API endpoint** - Set the API base URL for your environment: + Set the base URL in your environment: ```bash export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" From 3238fefa5628ec9bfe9e4b8f3e9bc36c54dc4d5d Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 11 Sep 2025 10:57:08 +0100 Subject: [PATCH 09/10] chore: change title to give space for the CLI --- getting-started/get-started-devops-as-code.md | 4 ++-- getting-started/page-index/page-index.js | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index 8df4ac02c7..a7882b458a 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -1,5 +1,5 @@ --- -title: "DevOps with Tiger Cloud REST API" +title: "DevOps as code with Tiger Cloud" excerpt: "Configure secure authentication and create a new database service using the Tiger Cloud REST API" keywords: - authentication @@ -15,7 +15,7 @@ tags: import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; -# DevOps with Tiger Cloud REST API +# DevOps as code with Tiger Cloud [$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read replicas. diff --git a/getting-started/page-index/page-index.js b/getting-started/page-index/page-index.js index a8681649f7..501845fbd7 100644 --- a/getting-started/page-index/page-index.js +++ b/getting-started/page-index/page-index.js @@ -23,7 +23,7 @@ module.exports = [ excerpt: "Create a Tiger Cloud service and connect to it", }, { - title: "DevOps with Tiger Cloud REST API", + title: "DevOps as code with Tiger Cloud", href: "get-started-devops-as-code", excerpt: "Set up secure authentication for the TigerData Cloud REST API and create your first service", }, From 1fac0458db3a2edfb58b64dc2b62b9faf2a4208f Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 30 Sep 2025 15:32:25 +0200 Subject: [PATCH 10/10] chore: updates on review. --- _partials/_devops-rest-api-get-started.md | 158 ++++++++++++++++ getting-started/get-started-devops-as-code.md | 179 +----------------- 2 files changed, 162 insertions(+), 175 deletions(-) create mode 100644 _partials/_devops-rest-api-get-started.md diff --git a/_partials/_devops-rest-api-get-started.md b/_partials/_devops-rest-api-get-started.md new file mode 100644 index 0000000000..e44dd82262 --- /dev/null +++ b/_partials/_devops-rest-api-get-started.md @@ -0,0 +1,158 @@ +import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; + +[$REST_LONG][rest-api-reference] is a comprehensive RESTful API you use to manage $CLOUD_LONG resources +including VPCs, $SERVICE_SHORTs, and read replicas. + +This page shows you how to set up secure authentication for the $REST_LONG and create your first $SERVICE_SHORT. + +## Prerequisites + + + +* Install [curl][curl]. + + +## Configure secure authentication + +$REST_LONG uses HTTP Basic Authentication with access keys and secret keys. All API requests must include +proper authentication headers. + + + +1. **Set up API credentials** + + 1. In $CONSOLE [copy your project ID][get-project-id] and store it securely using an environment variable: + + ```bash + export TIGERDATA_PROJECT_ID="your-project-id" + ``` + + 1. In $CONSOLE [create your client credentials][create-client-credentials] and store them securely using environment variables: + + ```bash + export TIGERDATA_ACCESS_KEY="Public key" + export TIGERDATA_SECRET_KEY="Secret key" + ``` + +1. **Configure the API endpoint** + + Set the base URL in your environment: + + ```bash + export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" + ``` + +1. **Test your authenticated connection to $REST_LONG by listing the $SERVICE_SHORTs in the current $PROJECT_LONG** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ + -H "Content-Type: application/json" + ``` + + This call returns something like: + - No $SERVICE_SHORTs: + ```terminaloutput + []% + ``` + - One or more $SERVICE_SHORTs: + + ```terminaloutput + [{"service_id":"a59clooxoe","project_id":"c8nmagk8zh","name":"events", + "region_code":"eu-central-1","service_type":"TIMESCALEDB", + "created":"2025-09-09T08:37:15.816443Z","paused":false,"status":"READY", + "resources":[{"id":"101228","spec":{"cpu_millis":500,"memory_gbs":2,"volume_type":""}}], + "metadata":{"environment":"DEV"},"endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com", + "port":12345}}] + ``` + + + + +## Create your first $SERVICE_LONG + +Create a new $SERVICE_SHORT using the $REST_LONG: + + + +1. **Create a $SERVICE_SHORT using the POST endpoint** + ```bash + curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-first-service", + "service_type": "TIMESCALEDB", + "region_code": "us-east-1", + "replica_count": 1, + "cpu_millis": 1000, + "memory_gbs": 4 + }' + ``` + $CLOUD_LONG creates a Development environment for you. That is, no delete protection, high-availability, spooling or + read-replication. You see something like: + ```terminaloutput + { + "service_id":"asdfasdfasdf","project_id":"asdasdfasf","name":"my-first-service", + "region_code":"us-east-1", "service_type":"TIMESCALEDB", + "created":"2025-09-09T09:24:31.997767396Z", "paused":false,"status":"READY", + "resources":[{"id":"101240", + "spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], + "metadata":{"environment":"PROD"}, + "endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com","port":123435}, + "initial_password":"very-secret", + "ha_replicas":{"sync_replica_count":0,"replica_count":1} + } + ``` + +1. Save `service_id` from the response to a variable: + ```bash + # Extract service_id from the JSON response + export SERVICE_ID="service_id-from-response" + ``` + +1. **Check the configuration for the ** + + ```bash + curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ + -u "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" \ + -H "Content-Type: application/json" + ``` +You see something like: + ```terminaloutput + {"service_id":"tgrservice","project_id":"tgrproject","name":"my-first-service","region_code":"us-east-1", + "service_type":"TIMESCALEDB","created":"2025-09-30T12:08:54.438785Z","paused":false,"status":"READY", + "resources":[{"id":"102879","spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], + "metadata":{"environment":"DEV"},"endpoint":{"host":"ohhhh.yeahhhhh.tsdb.cloud.timescale.com","port":33867}, + "ha_replicas":{"sync_replica_count":0,"replica_count":1}} + ``` + + + +And that is it, you are ready to use the [$REST_LONG][rest-api-reference] to manage your +$SERVICE_SHORTs in $CLOUD_LONG. + +## Security best practices + +Follow these security guidelines when working with the $REST_LONG: + +- **Credential management** + - Store API credentials as environment variables, not in code + - Use credential rotation policies for production environments + - Never commit credentials to version control systems + +- **Network security** + - Use HTTPS endpoints exclusively for API communication + - Implement proper certificate validation in your HTTP clients + - Consider IP allowlisting for production API access + +- **Data protection** + - Use secure storage for service connection strings and passwords + - Implement proper backup and recovery procedures for created services + - Follow data residency requirements for your region + +[rest-api-reference]: /api/:currentVersion:/api-reference/ +[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings +[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id +[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials +[curl]: https://curl.se/ \ No newline at end of file diff --git a/getting-started/get-started-devops-as-code.md b/getting-started/get-started-devops-as-code.md index a7882b458a..53b841e78f 100644 --- a/getting-started/get-started-devops-as-code.md +++ b/getting-started/get-started-devops-as-code.md @@ -13,181 +13,10 @@ tags: - authentication --- -import RESTPrereqs from "versionContent/_partials/_prereqs-cloud-account-only.mdx"; +import RESTGS from "versionContent/_partials/_devops-rest-api-get-started.mdx"; -# DevOps as code with Tiger Cloud +# DevOps as code with $CLOUD_LONG -[$CLOUD_LONG REST API][rest-api-reference] is a comprehensive RESTful API you use to manage Tiger Cloud resources including VPCs, services, and read -replicas. + -This page shows you how to set up secure authentication for the TigerData Cloud REST API and create your first service. - -## Prerequisites - - - -* Install [curl][curl]. - - -## Configure secure authentication - -$CLOUD_LONG REST API uses HTTP Basic Authentication with access keys and secret keys. All API requests must include -proper authentication headers. - - - -1. **Set up API credentials** - - 1. In $CONSOLE [copy your project ID][get-project-id] and store it securely using an environment variable: - - ```bash - export TIGERDATA_PROJECT_ID="your-project-id" - ``` - - 1. In $CONSOLE [create your client credentials][create-client-credentials] and store them securely using environment variables: - - ```bash - export TIGERDATA_ACCESS_KEY="Public key" - export TIGERDATA_SECRET_KEY="Secret key" - ``` - -1. **Configure the API endpoint** - - Set the base URL in your environment: - - ```bash - export API_BASE_URL="https://console.cloud.timescale.com/public/api/v1" - ``` - -1. **Test your authenticated connection to $CLOUD_LONG REST API by listing services** - - ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" - ``` - - This call returns something like: - - No services: - ```terminaloutput - []% - ``` - - One or more services: - - ```terminaloutput - [{"service_id":"a59clooxoe","project_id":"c8nmagk8zh","name":"events", - "region_code":"eu-central-1","service_type":"TIMESCALEDB", - "created":"2025-09-09T08:37:15.816443Z","paused":false,"status":"READY", - "resources":[{"id":"101228","spec":{"cpu_millis":500,"memory_gbs":2,"volume_type":""}}], - "metadata":{"environment":"DEV"},"endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com", - "port":12345}}] - ``` - - - - -## Create your first service - -Create a new database service using the Tiger Cloud REST API with secure configuration. - - - -1. **Define the service creation payload in a JSON file** - ```bash - cat > service-config.json << 'EOF' - { - "name": "my-first-service", - "service_type": "TIMESCALEDB", - "region_code": "us-east-1", - "replica_count": 1, - "cpu_millis": 1000, - "memory_gbs": 4 - } - EOF - ``` - -1. **Submit service creation request** - - 1. Create the service using the POST endpoint: - ```bash - curl -X POST "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d @service-config.json - ``` - $CLOUD_LONG creates a production environment for you. You see something like: - ```terminaloutput - { - "service_id":"asdfasdfasdf","project_id":"asdasdfasf","name":"my-first-service", - "region_code":"us-east-1", "service_type":"TIMESCALEDB", - "created":"2025-09-09T09:24:31.997767396Z", "paused":false,"status":"READY", - "resources":[{"id":"101240", - "spec":{"cpu_millis":1000,"memory_gbs":4,"volume_type":""}}], - "metadata":{"environment":"PROD"}, - "endpoint":{"host":"oh.yeah.tsdb.cloud.timescale.com","port":123435}, - "initial_password":"very-secret", - "ha_replicas":{"sync_replica_count":0,"replica_count":1} - } - ``` - - - 2. Save `service_id` from the response to a variable: - ```bash - # Extract service_id from the JSON response - export SERVICE_ID="service_id-from-response" - ``` - -1. **Change the environment from production to development** - - ```bash - curl -X GET "${API_BASE_URL}/projects/${TIGERDATA_PROJECT_ID}/services/${SERVICE_ID}" \ - -H "Authorization: Basic $(echo -n "${TIGERDATA_ACCESS_KEY}:${TIGERDATA_SECRET_KEY}" | base64)" \ - -H "Content-Type: application/json" \ - -d '{"environment": "DEV"}' - ``` - You see something like: - ```terminaloutput - { - "message": "Environment set successfully" - } - ``` - - - -And that is it, you are ready to use the [$CLOUD_LONG REST API][rest-api-reference] to manage your -$SERVICE_SHORTs in $CLOUD_LONG. - -## Security best practices - -Follow these security guidelines when working with the Tiger Cloud REST API: - -- **Credential management** - - Store API credentials as environment variables, not in code - - Use credential rotation policies for production environments - - Limit credential scope to minimum required permissions - - Never commit credentials to version control systems - -- **Network security** - - Use HTTPS endpoints exclusively for API communication - - Implement proper certificate validation in your HTTP clients - - Consider IP allowlisting for production API access - - Monitor API access logs for suspicious activity - -- **Access control** - - Create dedicated service accounts for automated API access - - Use principle of least privilege for API key permissions - - Regularly audit and review API access patterns - - Implement proper session management for interactive applications - -- **Data protection** - - Encrypt sensitive data before API transmission when applicable - - Use secure storage for service connection strings and passwords - - Implement proper backup and recovery procedures for created services - - Follow data residency requirements for your region - - -[rest-api-reference]: /api/:currentVersion:/api-reference/ -[rest-api-credentials]: https://console.cloud.timescale.com/dashboard/settings -[get-project-id]: /integrations/:currentVersion:/find-connection-details/#find-your-project-and-service-id -[create-client-credentials]: /integrations/:currentVersion:/find-connection-details/#create-client-credentials -[curl]: https://curl.se/ \ No newline at end of file +[rest-api-reference]: /api/:currentVersion:/api-reference/ \ No newline at end of file