Skip to content

api.mdx

Latest commit

 

History

History
146 lines (87 loc) · 5.21 KB

api.mdx

File metadata and controls

146 lines (87 loc) · 5.21 KB
Raw
title Gateway API Communication
description Backend communication patterns and URL management for CLI commands
sidebar API
icon Globe

Gateway API Communication

The DeployStack Gateway CLI manages backend communication automatically through stored configuration and credential management. This guide covers how CLI commands interact with the backend and manage different environments.

Backend URL Management

Automatic URL Storage

When users authenticate with the gateway, the backend URL is automatically stored alongside their credentials. This eliminates the need to specify the backend URL for every command after initial login.

Storage Location:

  • Primary: macOS Keychain, Windows Credential Manager, or Linux Secret Service
  • Fallback: Encrypted file at ~/.deploystack/credentials.enc

The backend URL is stored as part of the StoredCredentials object and persists across CLI sessions.

URL Resolution Priority

CLI commands resolve the backend URL using this priority order:

  1. Command-line override - --url flag when provided
  2. Stored URL - URL saved during authentication
  3. Default fallback - https://cloud.deploystack.io

This approach supports both development workflows with local backends and production usage seamlessly.

Environment Detection

The gateway automatically adapts behavior based on the backend URL:

Production Mode (https://cloud.deploystack.io):

  • Strict HTTPS enforcement
  • Full SSL certificate validation
  • Standard error messages

Development Mode (localhost or custom URLs):

  • HTTP connections allowed for localhost
  • Development-specific error messages
  • Additional debugging context

Command Implementation Patterns

Authentication Check

All API-dependent commands should verify authentication before making requests. The credential storage handles token validation and expiration checking automatically.

Backend URL Usage

Commands should retrieve stored credentials and use the embedded backend URL rather than requiring URL parameters. The URL resolution pattern ensures consistency across all commands.

Error Handling

Different backend environments may return different error formats. Commands should handle both production and development error responses gracefully.

API Client Configuration

Credential Integration

The API client accepts stored credentials and automatically extracts the appropriate backend URL. No additional URL configuration is required when credentials contain the backend information.

Request Headers

All authenticated requests include:

  • Bearer token authentication
  • User-Agent identification
  • Content-Type specification

Timeout Handling

Network operations include appropriate timeouts with different values for various operation types:

  • OAuth callback operations
  • API requests
  • Token refresh operations

Development Workflow

Local Backend Testing

Developers working with local backends can authenticate once and have all commands automatically use the development server:

The authentication flow stores the development URL, and subsequent commands use it automatically without additional configuration.

URL Override Capability

Commands maintain --url override options for testing different backends or switching environments temporarily without re-authentication.

Environment Switching

To switch between environments, users can either:

  • Re-authenticate with a different backend URL
  • Use command-line URL overrides for temporary testing

Security Considerations

URL Validation

Backend URLs are validated during authentication to ensure they meet security requirements for the target environment.

Credential Isolation

Each backend URL maintains separate credential storage, preventing credential leakage between development and production environments.

HTTPS Enforcement

Production environments enforce HTTPS communication, while development environments allow HTTP for localhost testing.

Error Response Handling

Network Errors

Commands should provide helpful error messages that include the backend URL being used, especially for development environments where connectivity issues are common.

Authentication Errors

Token expiration and invalid token errors should guide users to re-authenticate, preserving their backend URL preference.

Backend-Specific Errors

Different backend versions or configurations may return varying error formats. Commands should handle these gracefully and provide consistent user experience.

Integration Guidelines

New Command Development

When developing new CLI commands that interact with the backend:

  1. Use the credential storage system for authentication
  2. Extract backend URL from stored credentials
  3. Implement URL override options for flexibility
  4. Handle environment-specific error cases
  5. Provide clear error messages with backend context

API Client Usage

The DeployStack API client handles most backend communication complexity automatically. Commands should focus on business logic rather than HTTP details.

Testing Considerations

Test commands against both production and development backends to ensure consistent behavior across environments. The URL storage system supports this testing workflow naturally.