README.md•5.78 kB
# API Profiles
This directory contains YAML configuration files for different APIs that can be deployed using this project. Each profile defines the API configuration including endpoints, authentication, and deployment settings.
## Quick Start
### List Available Profiles
```bash
just list-profiles
```
### Deploy with a Profile
```bash
# Deploy to AWS Lambda
just deploy-profile zoho-crm
# Test locally with Docker
just docker-run-profile petstore
just test
# Test deployed Lambda
just test-profile zoho-crm
```
## Profile Structure
Each profile is a YAML file with the following structure:
```yaml
api_name: MyAPI # Name for deployment (alphanumeric + dots)
api_base_url: https://api.example.com/v1 # Base URL for API requests
api_spec_url: https://api.example.com/openapi.json # OpenAPI spec location
# Authentication (choose one)
auth_type: none # Options: none, basic, bearer, api_key, cognito, zoho
# Optional authentication fields (based on auth_type)
auth_token: ${MY_API_TOKEN} # Bearer/Zoho token from environment variable
```
## Available Profiles
### petstore.yaml
Swagger Petstore API - perfect for testing and demonstrations. No authentication required.
**Usage:**
```bash
just deploy-profile petstore
```
### zoho-crm.yaml
Zoho CRM API v8.0 Records API. Requires OAuth authentication.
**Setup:**
1. Get your OAuth token from Zoho (access or refresh token)
2. Set environment variable: `export ZOHO_OAUTH_TOKEN="your-token-here"`
3. Uncomment `auth_token` line in the profile
4. Deploy: `just deploy-profile zoho-crm`
**Regional Endpoints:**
- US: `https://www.zohoapis.com`
- Canada: `https://www.zohoapis.ca`
- EU: `https://www.zohoapis.eu`
- India: `https://www.zohoapis.in`
- Australia: `https://www.zohoapis.com.au`
### profile-template.yaml
Template for creating new API profiles. Copy and customize for your API.
## Creating a New Profile
1. Copy the template:
```bash
cp profiles/profile-template.yaml profiles/my-api.yaml
```
2. Edit the profile with your API details:
```yaml
api_name: MyAPI
api_base_url: https://api.example.com
api_spec_url: https://api.example.com/openapi.json
auth_type: bearer
auth_token: ${MY_API_TOKEN}
```
3. Set any required environment variables:
```bash
export MY_API_TOKEN="your-token-here"
```
4. Deploy:
```bash
just deploy-profile my-api
```
## Environment Variable Substitution
Profiles support environment variable substitution using `${VAR_NAME}` syntax:
```yaml
auth_token: ${ZOHO_OAUTH_TOKEN} # Will be replaced with actual token value
auth_api_key: ${API_KEY}
```
This allows you to:
- Keep sensitive credentials out of version control
- Use different credentials for different environments
- Share profile configurations safely
## Authentication Types
### none
No authentication required.
```yaml
auth_type: none
```
### bearer
Bearer token authentication (Authorization: Bearer TOKEN).
```yaml
auth_type: bearer
auth_token: ${MY_API_TOKEN}
```
### zoho
Zoho OAuth authentication (Authorization: Zoho-oauthtoken TOKEN).
```yaml
auth_type: zoho
auth_token: ${ZOHO_OAUTH_TOKEN} # Access or refresh token
```
### basic
HTTP Basic authentication.
```yaml
auth_type: basic
auth_username: ${API_USERNAME}
auth_password: ${API_PASSWORD}
```
### api_key
API key in header or query parameter.
```yaml
auth_type: api_key
auth_api_key: ${API_KEY}
auth_api_key_name: X-API-Key # Header/param name
auth_api_key_in: header # "header" or "query"
```
### cognito
AWS Cognito authentication.
```yaml
auth_type: cognito
auth_cognito_user_pool_id: ${COGNITO_USER_POOL_ID}
auth_cognito_client_id: ${COGNITO_CLIENT_ID}
auth_cognito_username: ${COGNITO_USERNAME}
auth_cognito_password: ${COGNITO_PASSWORD}
```
## Deployment Stack Naming
The deployed CloudFormation stack name is automatically generated from the `api_name`:
- Format: `openapi-mcp-{api_name_lowercase}`
- Example: `api_name: ZohoCRM` → stack: `openapi-mcp-zohocrm`
- Non-alphanumeric characters (except dots) are replaced with dashes
## Best Practices
1. **Keep credentials secure**: Use environment variables, never commit tokens to git
2. **Use descriptive names**: Make `api_name` clear and meaningful
3. **Document requirements**: Add comments about auth setup and regional options
4. **Test locally first**: Use `docker-run-profile` before deploying to Lambda
5. **Production secrets**: Store sensitive tokens in AWS Secrets Manager for production deployments
## Examples
### Test Locally
```bash
# Build Docker image
just docker-build
# Run with profile
just docker-run-profile petstore
# Run tests
just test
# Stop container
just docker-stop
```
### Deploy to AWS Lambda
```bash
# First time: bootstrap CDK
just bootstrap
# Deploy with profile
just deploy-profile zoho-crm
# Test deployed function
just test-profile zoho-crm
# View logs
API_NAME=ZohoCRM just logs
# Destroy stack
API_NAME=ZohoCRM just destroy
```
## Troubleshooting
### Profile not found
```bash
# Check available profiles
just list-profiles
# Verify file exists
ls profiles/my-api.yaml
```
### Environment variable not set
```bash
# Profile loader will warn about missing variables
just _load_profile my-api
# Set the required variable
export MY_API_TOKEN="your-token"
```
### Authentication errors
- Verify credentials are correct and not expired
- Check the auth_type matches your API's requirements
- For Zoho: Ensure you're using the correct regional endpoint
- Test API credentials directly with curl before deploying
## Contributing
When adding new profiles:
1. Use the template as a starting point
2. Include helpful comments about setup requirements
3. Document any regional or environment-specific settings
4. Add an entry to this README