npm package: @glideapps/uapi
Description: CLI tool for managing local development of unified API services
Author: Glide
Latest version: 2.0.0

# @glideapps/uapi

CLI tool for managing local development of unified API services.

## Installation

### Install globally from npm
```bash
npm install -g @glideapps/uapi
```

### Install from source
```bash
# From the packages/uapi directory
npm install
npm run build
npm link
```

## Commands

### Service Management

| Command | Description |
|---------|-------------|
| `uapi services:list` | List all available services |
| `uapi services:register` | Register new service with full integration setup |
| `uapi services:add-routes <service>` | Add new routes to existing service |
| `uapi services:deregister <service>` | Deregister service from configuration |

### API Operations

| Command | Description |
|---------|-------------|
| `uapi api:start` | Start the Envoy API proxy |
| `uapi api:stop` | Stop the Envoy API proxy |
| `uapi api:regenerate` | Regenerate API configuration and routes |
| `uapi api:restitch` | Merge OpenAPI specifications into unified spec |

## Quick Start Examples

```bash
# List all available services
uapi services:list

# Register a new service (full onboarding workflow)
uapi services:register

# Start the API gateway
uapi api:start

# Stop the API gateway
uapi api:stop

# Add routes to existing service
uapi services:add-routes my-service

# Regenerate API configuration after changes
uapi api:regenerate

# Merge OpenAPI specs into unified specification
uapi api:restitch
```

## Service Registration Workflow

The `uapi services:register` command provides a complete onboarding experience:

1. **Service Configuration**: Prompts for repository, routes, build/run commands, and local development settings
2. **OpenAPI Spec Fetching**: Automatically downloads the service's OpenAPI specification
3. **Unified Spec Generation**: Merges all service specs into a unified OpenAPI specification
4. **Route Configuration**: Updates API gateway routes and Envoy configuration
5. **GitHub Integration**: Sets up GitHub workflows for automatic OpenAPI spec updates
6. **Pull Request**: Automatically creates PR with unified API integration changes

## Configuration

Services are configured in `services.yaml`. The tool automatically searches for this file in the current directory or any parent directory.

### Example Service Configuration
```yaml
services:
  my_service:
    repository: https://github.com/org/my-service
    openapi_spec: openapi.yaml
    service_owner: org/team-name
    routes:
      - /api/v1/my-service
      - /my-service
    development:
      build_command: npm install    # Optional
      run_command: npm run dev
    hosts:
      localhost:
        host: host.docker.internal
        port: 8080
        timeout: 30s
        health_check_path: /health
```

## Key Features

- **Complete Service Onboarding**: Single command setup from registration to PR creation
- **Automatic OpenAPI Integration**: Fetches, merges, and unifies API specifications
- **GitHub Workflow Integration**: Automatically sets up workflows for spec synchronization
- **Route Management**: Add and manage service routes with conflict detection
- **Configuration Management**: Regenerate API gateway configuration and routing

## OpenAPI Integration

- **Individual Specs**: Service OpenAPI specs are stored in `openapi/{service-name}.yml`
- **Unified Spec**: Combined specification available at `openapi/unified-spec.yml`
- **Automatic Merging**: Specs are automatically merged when services are registered or updated
- **Swagger UI**: Use the provided Swagger server to view unified API documentation

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev -- services:list

# Build for distribution
npm run build

# Test built version
node dist/cli.js services:list
```

## License

MIT