🔌 Descoberta, Inventário e Mapeamento de APIs & Service Mesh

Esta skill orienta a inteligência artificial a atuar como Especialista em Mapeamento de Contratos de API, Portais de Desenvolvedor e Service Meshes, catalogando endpoints REST, GraphQL, gRPC, políticas de gateway, dependências entre serviços e governança de APIs corporativas.

---

🌐 1. Arquitetura de Mapeamento de APIs e Catálogo Centralizado

A governança de APIs moderna centraliza os contratos de serviço em catálogos unificados enquanto monitora o tráfego em tempo de execução nos gateways e malhas de serviço:

flowchart TD
    subgraph Development["Design & Código"]
        OPENAPI["Especificação OpenAPI / Swagger (YAML/JSON)"]
        GRPC_PROTO["Arquivos Protobuf (.proto)"]
        GRAPHQL_SCHEMA["GraphQL Schema (.graphql)"]
    end

    subgraph DeveloperPortals["Catálogo de Software & Documentação"]
        BACKSTAGE["Spotify Backstage (Software Catalog & System Model)"]
        REDOC["Redoc & Swagger UI (API Specs)"]
    end

    subgraph Gateways["API Gateways & Roteamento L7"]
        KONG["Kong Gateway (Plugins, Rotas & Consumidores)"]
        APISIX["Apache APISIX (Dynamic Route Matching)"]
        GRAVITEE["Gravitee.io / WSO2 API Manager"]
    end

    subgraph ServiceMeshMesh["Malha de Serviços & Frameworks"]
        KIALI["Kiali (Istio/Linkerd Topology & mTLS Graph)"]
        WEAVER["Service Weaver (Distributed App Framework)"]
    end

    Development --> DeveloperPortals
    Development --> Gateways
    Gateways --> ServiceMeshMesh
    ServiceMeshMesh -.->|"Live Metrics & Traces"| BACKSTAGE

---

🛠️ 2. Ferramentas Especialistas de Mapeamento de APIs

1. Spotify Backstage (O Padrão de Software Catalog e IDP)

• Conceito: Plataforma aberta desenvolvida pelo Spotify para construção de Portais Internos do Desenvolvedor (Internal Developer Platforms - IDP). Mapeia entidades de software através de manifestos YAML (catalog-info.yaml), estabelecendo relacionamentos de System, Domain, Component, API, Resource e User/Group.
• Exemplo de Manifesto catalog-info.yaml para Mapeamento de API e Dependências:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: Serviço central de processamento de pedidos
  tags:
    - java
    - spring-boot
    - e-commerce
spec:
  type: service
  lifecycle: production
  owner: group:checkout-team
  system: ecommerce-core
  providesApis:
    - order-api-v1
  consumesApis:
    - payment-api-v2
    - inventory-api-v1
  dependsOn:
    - resource:order-postgres-db
    - resource:order-events-kafka-topic
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api-v1
  description: API REST de gerenciamento de pedidos
spec:
  type: openapi
  lifecycle: production
  owner: group:checkout-team
  system: ecommerce-core
  definition:
    $text: ./openapi.yaml

2. OpenAPI / Swagger & Redoc

• OpenAPI 3.1: Especificação padrão da indústria para descrição de contratos HTTP/REST, permitindo geração de clientes, servidores e testes de contrato.
• Redoc: Mecanismo de renderização de documentação estática responsiva de alta performance a partir de especificações OpenAPI.

# Gerar documentação HTML autônoma do OpenAPI
npx @redocly/cli build-docs openapi.yaml -o api-docs.html

3. API Gateways (Kong, Apache APISIX, Gravitee, WSO2)

• Kong Gateway: Mapeia serviços upstream, rotas, plugins de autenticação (OAuth2, Key-Auth), rate limiting e CORS via API administrativa ou declaração declarativa decK (kong.yaml).
• Apache APISIX: Gateway nativo de nuvem baseado em Nginx/Lua e etcd, com suporte a roteamento dinâmico e plugins de observabilidade OpenTelemetry e Prometheus.
• Gravitee.io & WSO2 API Manager: Plataformas completas de ciclo de vida de APIs cobrindo monetização, controle de acesso baseado em planos/assinaturas e análise de tráfego de desenvolvedores.

4. Service Weaver (Google)

• Conceito: Framework distribuído para Go que permite escrever aplicações como um monólito modular e fazer o deploy transparente como múltiplos microsserviços, com descoberta e comunicação IPC otimizada pelo runtime do framework.

5. Kiali (Istio/Linkerd API Topology)

• Conceito: Inspeciona a malha de serviços em tempo real, mapeando as rotas de tráfego de API entre pods, taxas de erro HTTP por versão de serviço e autenticação mTLS inter-serviços.

---

📊 3. Modelo de Entidades C4 / Backstage para APIs

Ao modelar ecossistemas de APIs, estruture as relações de acordo com o modelo de catálogo de serviços:

Entidade	Definição	Relacionamentos
Domain	Domínio de negócio macro (ex: Vendas, Logística)	Contém múltiplos Systems
System	Conjunto coeso de serviços que entregam uma capacidade	Agrupa Components e Resources
Component	Unidade de software executável (Microsserviço, Frontend, Lambda)	providesApis, consumesApis, dependsOn
API	Contrato formal de interface (OpenAPI, Protobuf, GraphQL)	Implementada por um Component
Resource	Infraestrutura externa persistente ou de mensageria	Banco de dados, Tópico Kafka, Bucket S3

---

🎯 4. Boas Práticas de Governança de APIs

• Design-First com OpenAPI: Escreva e valide a especificação OpenAPI antes da implementação do código-fonte para alinhar consumidores e produtores.
• Detecção de Quebra de Contrato (Contract Testing): Utilize testes de contrato (ex: Pact) para garantir que alterações em APIs produtoras não quebrem microsserviços consumidores.
• Inventário Automático no CI/CD: Valide e publique automaticamente as especificações de API no Backstage ou portal de desenvolvedor durante o pipeline de release.