Case Study: Building a Scalable Developer API Portal with AWS API Gateway, Kong, and Terraform

When a fintech scales from a product into a platform, it encounters an invisible barrier: its own APIs.
At first, internal endpoints serve a single mobile app or dashboard. But as partnerships grow — open banking, embedded finance, payment rails, data exchange — suddenly those internal APIs must face the world. And that’s when everything changes.

In fintech, an API is not just a technical interface. It’s a contract of trust.
Partners rely on it to handle money, verify identity, and maintain compliance. Regulators may audit it. Security teams scrutinize every header and token. A single missing field or ambiguous error message can derail integration timelines worth millions.

INSART’s challenge in this hypothetical scenario is to design an API ecosystem that not only works — but thrives.
The result: a Developer API Portal — a single pane of glass that turns raw endpoints into a well-governed, discoverable, testable ecosystem.

The Challenge: From Internal APIs to a Fintech Ecosystem

Imagine a fintech company that has grown beyond its original product. It now offers APIs for onboarding customers (KYC), managing accounts, retrieving balances, and initiating transactions. Each of these endpoints lives in different internal services. The documentation is scattered across Confluence pages and Postman collections. There’s no consistent authentication scheme; some APIs use API keys, others OAuth.

Partners want to integrate, but engineers keep replying, “Let us get back to you — the documentation is outdated.”
Integration teams spend weeks sending example payloads by email. The API might be excellent under the hood, but to the outside world, it feels fragmented and opaque.

This is where INSART would step in — not just to document APIs, but to productize them. The task is to design a system where external developers can explore endpoints in a sandbox, test requests in real time, retrieve sample payloads, and read unified docs — all in one place.

Our goal: a developer experience so smooth it feels invisible.

The Philosophy: Developer Experience as Infrastructure

At INSART, we treat developer experience (DX) as infrastructure.
It’s not a design layer that sits on top of engineering; it’s the bridge that turns APIs into business growth.

For fintechs, this is crucial. Partners who adopt your API become your distribution network.
If they struggle to understand or authenticate, they churn. If they integrate easily, they scale you.

We would start by defining three principles for the portal:

1. Self-discovery: Every endpoint should be discoverable through human-readable docs and machine-readable specifications.
2. Self-service: Developers should be able to generate keys, call sandbox endpoints, and manage quotas without waiting for human support.
3. Self-healing: When a new version is deployed, the portal should update automatically — no outdated documentation, no manual syncs.

In fintech, these three are not convenience features. They are compliance necessities.
APIs that serve payments, onboarding, or lending data must be traceable, auditable, and version-controlled. That philosophy drives every design decision downstream.

Designing the Foundation: API Contracts and Governance

Every successful API program begins with contract clarity. INSART would begin with OpenAPI 3.0 specifications for each service — a machine-readable blueprint of every path, parameter, schema, and authentication mechanism.

This contract is then stored in SwaggerHub, a collaborative platform where engineers, QA, product managers, and even legal reviewers can contribute feedback. SwaggerHub also becomes the source of truth for code generation, test scripts, and SDK scaffolding.

An example specification excerpt for an accounts endpoint might look like this:

openapi: 3.0.3
info:
  title: Fintech Partner API
  version: 1.0.0
  description: API for partner applications to access account and transaction data.
servers:
  - url: https://api.fintech-ecosystem.com/v1
    description: Production environment
  - url: https://sandbox.fintech-ecosystem.com/v1
    description: Sandbox environment
paths:
  /accounts/{accountId}/balance:
    get:
      summary: Retrieve account balance
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Account balance retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
components:
  schemas:
    Balance:
      type: object
      properties:
        accountId:
          type: string
        currency:
          type: string
        balance:
          type: number
          example: 10325.45

From this file, INSART’s automated tooling can generate:

• AWS API Gateway definitions
• Kong route configurations
• Postman collections
• Redoc and Swagger UI documentation pages

This architecture ensures that when one team updates an endpoint, all other representations — gateway, docs, SDKs — update automatically.

Infrastructure Blueprint: AWS API Gateway, Kong, and Terraform

Now comes the infrastructure.
We would create a layered design: Kong Gateway at the edge, AWS API Gateway as the internal router, and Terraform as the glue binding everything together.

Kong handles external traffic — authentication, rate limiting, and request transformations. API Gateway proxies internal microservices, enforces IAM-based policies, and exports structured logs to CloudWatch.

A simplified architecture diagram (textual representation):

[External Developer]
      |
      v
[Kong Gateway] --> [AWS API Gateway] --> [Lambda / ECS APIs]
      |
      v
[Developer Portal UI / Swagger / Redoc]

Terraform would provision this stack declaratively:

resource "aws_api_gateway_rest_api" "partner_api" {
  name        = "fintech-partner-api"
  description = "Public Partner API"
}

resource "kong_service" "partner_service" {
  name     = "partner-api"
  protocol = "https"
  host     = aws_api_gateway_rest_api.partner_api.execution_arn
  port     = 443
}

resource "kong_route" "partner_route" {
  service_name = kong_service.partner_service.name
  paths        = ["/v1"]
  methods      = ["GET", "POST", "PATCH", "DELETE"]
}

This setup allows us to re-deploy environments with identical configurations — sandbox, beta, and production — simply by running:

terraform apply -var="env=sandbox"

Every API key, rate limit, and usage plan is codified in version control. This not only accelerates deployment but also satisfies fintech compliance requirements around change management and traceability.

Bringing APIs to Life: Documentation and Interaction Layer

A static document isn’t enough; developers need to see and feel the API working.

That’s why INSART integrates Swagger UI and Redoc into a dynamic documentation portal.
Swagger UI allows real-time interaction — developers can authenticate and execute calls directly from the docs. Redoc provides a stable reference, elegant typography, and full-text search.

Example Swagger UI configuration hosted in the developer portal:

<!DOCTYPE html>
<html>
  <head>
    <title>Fintech API Portal</title>
    <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script>
      SwaggerUIBundle({
        url: "https://api.fintech-ecosystem.com/openapi.yaml",
        dom_id: "#swagger-ui",
        presets: [SwaggerUIBundle.presets.apis],
        layout: "BaseLayout"
      })
    </script>
  </body>
</html>

To complement it, we’d host Redoc for static reference, branded with the fintech’s colors:

<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
<redoc spec-url="https://api.fintech-ecosystem.com/openapi.yaml"></redoc>

This dual interface supports both experimentation and authority — Swagger for trying, Redoc for trusting.

Sandbox, Versioning, and Monitoring the API Lifecycle

The next piece of the puzzle is lifecycle management.
In fintech ecosystems, APIs must evolve without breaking partners. That means managing multiple live versions.

INSART’s solution would create distinct environments (v1, v2, beta) in AWS API Gateway. Each version is deployed as its own stage with its own usage plans and credentials.

A Terraform example for versioned stages:

resource "aws_api_gateway_deployment" "v1" {
  rest_api_id = aws_api_gateway_rest_api.partner_api.id
  stage_name  = "v1"
}

resource "aws_api_gateway_deployment" "v2" {
  rest_api_id = aws_api_gateway_rest_api.partner_api.id
  stage_name  = "v2"
}

Kong applies routing rules, directing requests to /v1 or /v2 based on the path.
Each request passes through API Gateway, which logs to CloudWatch. Log data is streamed to Grafana dashboards where product owners can visualize partner traffic, latency, and error trends.

For sandbox environments, we’d deploy a fully functional copy with mock data responses and token-based throttling. This allows developers to explore freely without touching production.

Continuous Integration and Automation

A world-class developer portal can’t rely on manual updates.
INSART would automate everything through GitHub Actions and Terraform Cloud pipelines.

When a developer merges an updated OpenAPI spec to the main branch, a pipeline triggers:

1. Validate the OpenAPI YAML syntax using spectral lint.
2. Publish the spec to SwaggerHub.
3. Regenerate Postman collections automatically via API.
4. Rebuild the documentation site (Swagger UI + Redoc).
5. Sync to the S3 bucket that hosts the public developer portal.
6. Invalidate the CloudFront cache to propagate updates instantly.

Sample pipeline segment:

- name: Validate OpenAPI spec
  run: npx @stoplight/spectral lint openapi.yaml

- name: Publish to SwaggerHub
  run: |
    curl -X POST "https://api.swaggerhub.com/apis/fintech/partner-api/1.0.0" \
      -H "Authorization: $SWAGGERHUB_TOKEN" \
      -H "Content-Type: application/yaml" \
      --data-binary "@openapi.yaml"

- name: Deploy docs to S3
  run: aws s3 sync ./public s3://developer-portal --delete

Every time documentation changes, the portal updates automatically — making it impossible for the docs to go stale.

The Strategic Payoff: Turning APIs into Ecosystem Growth

A well-structured developer portal isn’t just a convenience layer. It’s a revenue amplifier.
In fintech, time to integration equals time to revenue. The faster a partner can understand your API, test it, and go live, the faster your ecosystem grows.

With this architecture, INSART enables fintechs to:

• Cut partner onboarding time from weeks to hours.
• Ensure every API version is traceable and auditable.
• Empower developers with interactive documentation and instant sandbox access.
• Scale API management infrastructure with code, not manual setup.

The result is more than a portal. It’s a trust layer — an environment where partners feel safe experimenting and confident going live.

When every endpoint is documented, every error explained, and every spec validated, you don’t just have an API.
You have a platform others can depend on — and that’s how ecosystems are born.