aws-graphql-api

This is a GraphQL API designed to retrieve service information by querying the cluster name, service name, and the region where the cluster is deployed. The long-term plan for this API is to expand its capabilities to interact with various AWS resources.

Features

• 🚀 GraphQL API for AWS ECS service discovery
• 📊 Batch querying of multiple services in a single request
• 🌐 Support for multiple AWS regions
• 🔍 Detailed service information including:
  • Cluster ARN
  • Load balancer configurations
  • Container details
  • Service status
• ⚡ High performance with connection pooling
• 🔒 Secure with AWS IAM authentication
• 🐳 Docker support for easy deployment
• 🧪 Comprehensive test coverage

Key Benefits

• No Service Limits: Unlike AWS CLI's describe-services which is limited to 10 services per request, this API can handle unlimited services in a single query
• GraphQL Flexibility: Query only the fields you need, reducing response payload size
• Developer Friendly: Interactive GraphiQL playground for API exploration
• Container Ready: Easy deployment with Docker and provided Makefile

Docs

• Features
• Key Benefits
• Prerequisites
• Install
• Quick Start
• Running the tests
• Examples
• Contributing
• Acknowledgements
• License
• Contact

Getting Started

Prerequisites

• Node.js >= 20.9.0
• pnpm >= 10.11.0
• Docker (optional, for containerized deployment)

Install

Using pnpm (recommended):

# Install pnpm if you haven't already
npm install --global corepack@latest
corepack use pnpm@latest-10

# Install dependencies
pnpm install

Quick Start

Local Development

# Start the server locally
pnpm start

Using Docker

# Build and start the container
make up

# Check logs
make logs

# Test if the API is running
make test-api

# Stop the container
make down

Server will be running on:

Playground:

localhost:3000/graphiql

API Endpoint:

localhost:3000/graphql

Running the tests

Using pnpm:

pnpm test

Using Docker:

# Run tests in container
make test

Examples

Query:

query getService($serviceNames: String!, $clusterName: String!, $clusterDeployedRegion: String!){
  gdsServicesInfo(serviceNames: $serviceNames, clusterName: $clusterName, clusterDeployedRegion: $clusterDeployedRegion){
    clusterArn
    loadBalancers{
      containerName
      containerPort
      targetGroupArn
    }
  }
}

# Varables
{
  "serviceNames": "my-service-1,my-service-2",
  "clusterName": "my-cluster",
  "clusterDeployedRegion": "us-east-1"
}

The AWS SDK and CLI have certain limitations when it comes to retrieving service information. For instance, the describe-services command can only handle up to 10 services at a time. However, this API overcomes that limitation, allowing you to query information for as many services as you need in a single request. This makes it a more efficient and flexible tool for managing large-scale AWS environments.

More query examples will be added here.

Acknowledgements

Phil Hadviger have significantly contributed to the development of this API with their valuable suggestions and improvements.

Contributing

Please follow the guideline here

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

Apache License 2.0

Contact