View a markdown version of this page

REST API - AWS Prescriptive Guidance
REST APIData Flow - REST API

REST API

REST API

Data Flow - REST API

Step 1 — DNS Resolution (REST API Client → Amazon Route 53): The REST API Client resolves the API's custom domain name via Amazon Route 53, which serves as the DNS routing service. Route 53 returns the IP address associated with the API Gateway custom domain endpoint.

Step 2 — HTTPS Connection (REST API Client → Amazon API Gateway): The REST API Client establishes an HTTPS connection to Amazon API Gateway. The connection is secured using the SSL/TLS certificate managed by AWS Certificate Manager (ACM).

Step 3 — Certificate Association (Amazon Route 53 → AWS Certificate Manager): AWS Certificate Manager (ACM) provides the SSL/TLS certificate for the API Gateway's custom domain. This is a certificate association for HTTPS termination rather than a runtime API call — ACM ensures that all traffic between the client and API Gateway is encrypted in transit.

Step 4 — Authentication (REST API Client → Identity Provider): The REST API Client authenticates with the external Identity Provider (IdP) using an OIDC-compliant flow. For browser-based applications, this may involve a redirect-based authorization code flow. For machine-to-machine communication, this typically uses the client credentials grant. The IdP issues a JWT (JSON Web Token) / Bearer token upon successful authentication.

Step 5 — Authenticated Request (REST API Client → Amazon API Gateway): The REST API Client sends the API request to Amazon API Gateway with the JWT/Bearer token included in the Authorization header (e.g., Authorization: Bearer <token>). This is the primary API invocation carrying the business payload.

Step 6 — Token Validation (Amazon API Gateway → JWT/OIDC Authorizer Lambda): Amazon API Gateway invokes the Lambda authorizer (also known as a custom authorizer) to validate the JWT token. The Lambda authorizer is configured as a request-based or token-based authorizer that inspects the Authorization header.

Step 7 — JWKS Key Retrieval (JWT/OIDC Authorizer Lambda → Identity Provider): The JWT/OIDC Authorizer Lambda function calls the Identity Provider's .well-known/openid-configuration endpoint to retrieve the JSON Web Key Set (JWKS) containing the public keys. The authorizer uses these keys to verify the JWT token's signature, validate claims (issuer, audience, expiration), and generate an IAM policy that grants or denies access to the requested API resource.

Step 8 — Business Logic Execution (Amazon API Gateway → Backend Lambda): After the Lambda authorizer returns an "Allow" policy, Amazon API Gateway routes the request to the backend Lambda function. This Lambda function executes the REST API business logic serverlessly, processing the request and returning the response through API Gateway back to the client.

Infrastructure Organization: All AWS resources are deployed within a single AWS account. The Amazon API Gateway and both Lambda functions operate within a Virtual Private Cloud (VPC) for network isolation and security. The VPC boundary (blue border with padlock icon) encompasses the core compute components. Amazon Route 53 and AWS Certificate Manager operate at the account level. The Identity Provider (IdP) is external to the AWS Cloud boundary.

Architecture Highlights:

  • Serverless Design: Uses Lambda functions for scalable, event-driven compute with no infrastructure management

  • Zero-Trust Security: Every request is authenticated (IdP) and authorized (Lambda authorizer) before reaching business logic

  • Certificate Management: ACM automates SSL/TLS certificate provisioning and renewal for the custom domain

  • Standards-Based Authentication: Leverages OIDC/OAuth 2.0 and JWT for interoperable, industry-standard authentication

  • Separation of Concerns: Authentication (IdP), authorization (Lambda authorizer), and business logic (backend Lambda) are cleanly separated

Ontology Engineering REST API

Ontology Version Management REST API

Ontology Mapping Management (Source Schema → Ontology)

Rules Management (SHACL + SPARQL)

Semantic Metadata Management (Classes & Properties)

Semantic Search (Classes & Properties)

Metric Definition REST API

Supported MIME Types — Reference

Format

MIME Type

Use Case

Turtle

text/turtle

Default; human-readable, compact; preferred for ontology authoring and import/export

N-Quads

application/n-quads

Named graph support; recommended for versioned and provenance-aware exports

N-Triples

application/n-triples

Line-based, streaming-friendly; suited for large bulk exports

TriG

application/trig

Turtle + named graphs; natural fit for T-Box/A-Box separation in a single document

RDF/XML

application/rdf+xml

Legacy interoperability

JSON-LD

application/ld+json

Web/API-friendly; recommended for developer tooling and downstream API consumers

N3

text/n3

Superset of Turtle; includes rules support

Cross-Cutting Concerns

  • Content Negotiation: All serialization endpoints support Accept (response format) and Content-Type (request body format) headers per the MIME type table above. Default response format is text/turtle for RDF resources and application/json for metadata/list endpoints. Returns 406 Not Acceptable with a body listing supported types when an unsupported format is requested.

  • Named Graph Recommendations: Use application/n-quads or application/trig for exports requiring named graph provenance (e.g., versioned ontology snapshots, T-Box/A-Box separation).

  • Authentication: JWT/OIDC bearer token validated by API Gateway Lambda authorizer. Supports any OIDC-compliant identity provider including Amazon Cognito, Microsoft Entra ID, Okta, Auth0, Keycloak, and others. Required claims: sub, groups, act. Scope: semantic-layer:access.

  • API Versioning: All endpoints versioned via path prefix /v1/.

  • Audit Logging: All write operations emit structured events to CloudWatch Logs with ontologyId, operation, principalId, contentType, and timestamp.

  • Observability: OpenTelemetry traces propagated across all API calls; spans include ontology IRI, operation type, serialization format, and latency.