Football API Gateway Target

RapidAPI Football API integration for AWS Bedrock AgentCore Gateway. Deploy football data access to any gateway as an MCP-compatible target.

Overview

This project deploys RapidAPI Football API as an OpenAPI target to AWS Bedrock AgentCore Gateway, enabling AI agents to query:

• European top 5 league fixtures, results, and standings
• UEFA Champions League and Europa League data
• Player statistics (top scorers, assists)
• Domestic cup competitions

Key Features

• ✨ Fully Automated Deployment: Custom Resource automatically configures Gateway service role permissions
• Multi-Gateway Support: Deploy to multiple gateways with simple environment configuration
• Built-in League IDs: Common leagues pre-configured in tool descriptions, reducing API calls by 50%
• Shared Credentials: One RapidAPI key can be used across multiple gateway deployments
• CDK Asset Management: OpenAPI schema automatically uploaded to CDK staging bucket
• Secure Credentials: RapidAPI key stored in AWS Secrets Manager
• Idempotent: Safe to deploy multiple times, smart permission merging

Prerequisites

1. Node.js: >= 18.x
2. AWS CLI: Configured with credentials
3. AWS CDK: >= 2.100.0
4. RapidAPI Account: Active subscription to Football API
5. Existing Gateway: Target gateway must exist in your AWS account

Creating an AgentCore Gateway

If you don't have an existing gateway, you need to create one first. The gateway serves as a unified entry point for agents to access tools and resources through the Model Context Protocol (MCP).

Quick Start Options

Choose one of the following methods to create a gateway:

Method	Best For	Command Example
AWS Console	Visual interface, first-time setup	Web UI with step-by-step wizard
AWS CLI	Simple automation, IAM auth	aws bedrock-agentcore-control create-gateway --name my-gateway --authorizer-type AWS_IAM ...
AgentCore Toolkit	Automatic OAuth setup	agentcore create_mcp_gateway --region us-west-2 --name my-gateway

AWS CLI Example (IAM Authorization - Simplest)

aws bedrock-agentcore-control create-gateway \
  --name my-gateway \
  --role-arn arn:aws:iam::123456789012:role/MyAgentCoreServiceRole \
  --protocol-type MCP \
  --authorizer-type AWS_IAM \
  --region us-west-2

After Gateway Creation

Save these values from the output:

1. gatewayIdentifier → Use in .env file as GATEWAY_IDENTIFIER
2. gatewayUrl → MCP endpoint URL for connecting clients
3. roleArn → Gateway service role ARN

Important Notes

• Semantic Search: Can only be enabled during gateway creation (cannot be changed later)
• IAM Permissions: This CDK stack automatically adds credential provider permissions via Custom Resource
• Service Role: You only need basic gateway permissions; credential provider access is added automatically

📚 Complete Documentation:

• Gateway Overview
• Create Gateway - Console
• Create Gateway - API/CLI
• Service Role Permissions

Quick Start

1. Install Dependencies

npm install

2. Configure Environment

Copy .env.example to a gateway-specific env file:

cp .env.example .env.my-gateway.local
# Edit and set:
# - GATEWAY_IDENTIFIER: Your gateway identifier
# - CREDENTIAL_PROVIDER_NAME: Your credential provider name

3. One-Time Setup: Create Credential Provider

Step 1: Create the credential provider

# Create credential provider (only once for shared strategy)
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name FootballAPICredentialProvider \
  --description "RapidAPI Football API Key (shared)" \
  --profile default --region <YOUR_REGION>

Step 2: Store your RapidAPI key

Get your RapidAPI key from: https://rapidapi.com/api-sports/api/api-football

Then update the credential provider with your API key:

# IMPORTANT: Use bedrock-agentcore-control to update the API key
# DO NOT use secretsmanager put-secret-value directly
aws bedrock-agentcore-control update-api-key-credential-provider \
  --name FootballAPICredentialProvider \
  --api-key "YOUR_RAPID_API_KEY" \
  --profile default --region <YOUR_REGION>

Why use update-api-key-credential-provider?

• The secret is managed by the bedrock-agentcore-identity service
• Direct Secrets Manager operations may fail due to service ownership
• This command ensures proper formatting ({"apiKey": "..."}) automatically
• Provides better error messages for invalid keys

Common Issues:

• ❌ Wrong: {"api_key": "..."} or {"api_key_value": "..."}
• ✅ Correct: {"apiKey": "..."} (handled automatically by the command)
• If API calls return "Error/Missing application key", verify the key was updated successfully

4. Bootstrap CDK (First Time Only)

cdk bootstrap --profile default

5. Deploy to Gateway

./deploy.sh .env.my-gateway.local

Architecture

┌─────────────────────────────────────────────────────┐
│ AWS Bedrock AgentCore Gateway (pre-existing)        │
│                                                      │
│  ┌────────────────────────────────────────────┐    │
│  │ GatewayRoleUpdater (Custom Resource)       │    │
│  │  ↓ Automatically adds IAM permissions      │    │
│  │  ↓ to Gateway service role                 │    │
│  └────────────────────────────────────────────┘    │
│                                                      │
│  ┌────────────────────────────────────────────┐    │
│  │ FootballAPITarget (OpenAPI Target)         │    │
│  │                                             │    │
│  │  • OpenAPI Schema (CDK Asset → S3)         │    │
│  │  • API Key (Secrets Manager)               │    │
│  │  • Credential Provider: API_KEY            │    │
│  │  • Headers: x-rapidapi-key, x-rapidapi-host│    │
│  └────────────────────────────────────────────┘    │
│                                                      │
│  ┌────────────────────────────────────────────┐    │
│  │ Available Tools:                            │    │
│  │  • getFixtures                              │    │
│  │  • getStandings                             │    │
│  │  • getTopScorers                            │    │
│  │  • getTopAssists                            │    │
│  │  • getLeagues (fallback)                    │    │
│  └────────────────────────────────────────────┘    │
└──────────────────┬───────────────────────────────────┘
                   │ RapidAPI Key from Secrets Manager
                   ▼
            RapidAPI Football API v3
          (https://v3.football.api-sports.io)

Deployment Flow

cdk deploy
  ↓
1. GatewayRoleUpdater (Custom Resource)
   ├── Lambda checks Gateway service role
   ├── Adds missing IAM permissions
   └── ✅ Role updated automatically
  ↓
2. OpenAPI Schema Asset
   └── Upload to S3
  ↓
3. Gateway Target
   ├── Reference Gateway
   ├── Reference Credential Provider
   └── Link OpenAPI schema from S3
  ↓
✅ Target READY (fully automated)

Available Tools

1. getFixtures

Get match fixtures, results, and schedules.

Parameters:

• league (integer): League ID (see common IDs below)
• season (integer, required): Season year (e.g., 2024 for 2024/2025 season)
• date (string): Match date (YYYY-MM-DD)
• last (integer): Get last N matches
• next (integer): Get next N upcoming matches
• status (string): Match status (FT=Full Time, LIVE=In Progress, NS=Not Started)
• team (integer): Filter by team ID

Examples:

// Premier League last 10 matches
{ league: 39, season: 2024, last: 10 }

// Champions League next 5 matches
{ league: 2, season: 2024, next: 5 }

// La Liga matches on specific date
{ league: 140, season: 2024, date: "2024-11-10" }

// Live matches across all leagues
{ season: 2024, status: "LIVE" }

2. getStandings

Get league standings/table.

Parameters:

• league (integer, required): League ID
• season (integer, required): Season year
• team (integer): Specific team ID

Examples:

// Premier League standings
{ league: 39, season: 2024 }

// Serie A standings
{ league: 135, season: 2024 }

3. getTopScorers

Get top goal scorers.

Parameters:

• league (integer, required): League ID
• season (integer, required): Season year

Examples:

// Bundesliga top scorers
{ league: 78, season: 2024 }

4. getTopAssists

Get top assists leaders.

Parameters:

• league (integer, required): League ID
• season (integer, required): Season year

5. getLeagues

Search for leagues (use only for uncommon leagues).

Parameters:

• id (integer): Specific league ID
• name (string): Search by name
• country (string): Filter by country
• season (integer): Filter by season
• current (boolean): Active leagues only

Common League IDs

Top 5 European Leagues

• Premier League (England): 39
• La Liga (Spain): 140
• Serie A (Italy): 135
• Bundesliga (Germany): 78
• Ligue 1 (France): 61

European Competitions

• UEFA Champions League: 2
• UEFA Europa League: 3

Domestic Cups

• FA Cup (England): 45
• Copa del Rey (Spain): 143
• Coppa Italia (Italy): 137
• DFB Pokal (Germany): 81
• Coupe de France (France): 66

Optimization Strategy

The OpenAPI schema includes common league IDs in tool descriptions, enabling:

1. Direct Usage: AI agents can use league IDs immediately for common leagues
2. Reduced API Calls: No need to query getLeagues for popular competitions
3. Faster Response: Eliminates one API round-trip (200-500ms saved)
4. Quota Savings: Reduces API usage by ~50% for typical queries

Example Flow (Optimized):

User: "Get Premier League standings"
→ Agent directly calls: getStandings({ league: 39, season: 2024 })
→ API calls: 1

Example Flow (Unoptimized):

User: "Get Premier League standings"
→ Agent calls: getLeagues({ name: "Premier League" })
→ Agent calls: getStandings({ league: 39, season: 2024 })
→ API calls: 2 ❌

Season Parameter Guide

Football API uses year to represent seasons:

• 2024 = 2024/2025 season (August 2024 - May 2025)
• 2023 = 2023/2024 season (August 2023 - May 2024)
• 2022 = 2022/2023 season (August 2022 - May 2023)

Example: For matches in November 2024, use season: 2024 (current 2024/2025 season).

Quick Usage Examples

Check Premier League Standings

Tool: getStandings
Parameters: { "league": 39, "season": 2024 }

Get Today's Champions League Matches

Tool: getFixtures
Parameters: { "league": 2, "season": 2024, "date": "2024-11-10" }

Compare Top 5 Leagues' Top Scorers

# AI agent can call these in parallel:
getTopScorers({ "league": 39, "season": 2024 })   # Premier League
getTopScorers({ "league": 140, "season": 2024 })  # La Liga
getTopScorers({ "league": 135, "season": 2024 })  # Serie A
getTopScorers({ "league": 78, "season": 2024 })   # Bundesliga
getTopScorers({ "league": 61, "season": 2024 })   # Ligue 1

Common Errors

Rate Limit Exceeded

{ "errors": { "requests": "The request limit has been reached" } }

Solution: Upgrade RapidAPI plan or wait for quota reset.

Invalid League ID

{ "errors": { "league": "Invalid league id" } }

Solution: Use getLeagues to search for correct league ID.

No Data Returned

{ "results": 0, "response": [] }

Causes: Incorrect season, inactive league, or date out of range.

RapidAPI Rate Limits

• Free Plan: 100 requests/day
• Basic Plan: 500 requests/day ($10/month)
• Pro Plan: 5,000 requests/day ($35/month)

Monitor usage in RapidAPI dashboard: https://rapidapi.com/developer/dashboard

Project Structure

agentcore-gateway-targets/
├── schemas/
│   └── football-api-openapi.yaml       # OpenAPI 3.0 schema with embedded league IDs
├── lib/
│   └── football-gateway-stack.ts        # CDK Stack implementation
├── bin/
│   └── football-gateway-app.ts          # CDK App entry point
├── deploy.sh                            # Deployment script for CDK stack
├── package.json                         # Node.js dependencies
├── tsconfig.json                        # TypeScript configuration
├── cdk.json                             # CDK configuration
├── .env.example                         # Environment template
├── .env.*.local                         # Gateway-specific configs (git-ignored)
├── CLAUDE.md                            # Project documentation (environment-agnostic)
├── CLAUDE.local.md                      # Environment-specific notes (git-ignored)
└── README.md                            # This file

Development

Build

npm run build

Watch Mode

npm run watch

CDK Commands

# List stacks
cdk list

# Show diff
cdk diff

# Synthesize CloudFormation
cdk synth

# Deploy
cdk deploy --profile default

# Destroy (remove target)
cdk destroy --profile default

Verification

After deployment, verify the target:

# List all targets on your gateway
aws bedrock-agentcore-control list-gateway-targets \
  --gateway-identifier <YOUR_GATEWAY_IDENTIFIER> \
  --profile default --region <YOUR_REGION>

# Get specific target details
aws bedrock-agentcore-control get-gateway-target \
  --gateway-identifier <YOUR_GATEWAY_IDENTIFIER> \
  --target-id <TARGET_ID_FROM_OUTPUT> \
  --profile default --region <YOUR_REGION>

Troubleshooting

Target Creation Fails

1. Check gateway exists: aws bedrock-agentcore-control get-gateway --gateway-identifier <YOUR_GATEWAY_ID>
2. Verify credential provider exists and has correct name
3. Check CloudWatch Logs for errors
4. Validate OpenAPI schema syntax

API Calls Fail

1. Verify RapidAPI subscription is active
2. Check API key in Secrets Manager
3. Ensure x-rapidapi-host header matches
4. Review rate limit status

Schema Validation Errors

1. Ensure all operations have operationId
2. Avoid oneOf/anyOf/allOf constructs
3. Use simple parameter structures
4. Validate with OpenAPI validator: https://validator.swagger.io/

Cost Considerations

AWS Costs

• AgentCore Gateway: Pay per tool invocation
• Lambda (GatewayRoleUpdater): ~$0.01 per deployment (free tier eligible)
• CloudWatch Logs: Negligible (7-day retention)
• Secrets Manager: ~$0.40/month per secret
• S3 Storage: Negligible (schema file < 1KB)
• CloudFormation: No charge

RapidAPI Costs

• Free: 100 requests/day
• Basic: $10/month (500 requests/day)
• Pro: $35/month (5,000 requests/day)

References

• AWS Bedrock AgentCore Documentation
• OpenAPI Specification
• RapidAPI Football API
• API-Football Documentation

License

See LICENSE file in repository root.