aws-api

AWS API Integration

Skill para diseño, implementación y documentación de APIs HTTP en AWS usando API Gateway (REST y HTTP API), contratos OpenAPI, autenticación, autorización, validación de requests, manejo de errores y patrones de integración con servicios backend.

Principios fundamentales

• Toda API debe tener un contrato OpenAPI 3.0+ como fuente de verdad antes de escribir código.
• Preferir HTTP API (API Gateway v2) sobre REST API salvo que se necesiten features exclusivas de REST (WAF nativo, caching integrado, request validation server-side, usage plans).
• Cada endpoint debe tener definidos: método, path, request schema, response schemas (2xx, 4xx, 5xx), headers requeridos y content-type.
• Nunca exponer errores internos al cliente. Usar un envelope de error consistente.

Estructura de contrato OpenAPI

openapi: "3.0.3"
info:
  title: Mi API
  version: "1.0.0"
paths:
  /recurso:
    get:
      operationId: listarRecursos
      summary: Lista recursos paginados
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: nextToken
          in: query
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "500":
          $ref: "#/components/responses/InternalError"

Envelope de error estándar

Todas las respuestas de error deben seguir este formato:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El campo 'email' es requerido",
    "requestId": "abc-123",
    "details": []
  }
}

Códigos de error recomendados: VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, FORBIDDEN, CONFLICT, RATE_LIMITED, INTERNAL_ERROR.

Autenticación y autorización