Embedding API Endpoints

API documentation scattered across multiple tools creates confusion. Developers check Swagger for endpoints, Confluence for context, and code comments for the real behaviour. REST API endpoint blocks embed your API specifications directly in architecture documentation, keeping everything together and synchronised.

The Embedded API Approach

Traditional API documentation lives separately from architecture documentation:

Creating API Definitions

Before embedding endpoints, you need an API definition. NeoArc's REST API editor lets you define:

Embedding an Endpoint

When to Embed vs Link

Example: Embedded API Endpoints

Here are examples of embedded API endpoints from different domains, each demonstrating how endpoints connect to schemas with lineage tracking:

Library API Endpoint

This endpoint references the Book schema, which has ERD lineage to a database diagram:

E-Commerce API Endpoint

This endpoint references the Order schema and uses path parameters with lineage overrides:

Healthcare API Endpoint

This endpoint demonstrates graph database lineage. The Prescription schema traces back to nodes in a graph domain model:

Practical Patterns

Keeping APIs in Sync

Because NeoArc stores API definitions as files in your workspace:

API Definition Structure

NeoArc REST API definitions include:

Authentication Documentation

API definitions can specify authentication requirements. When you embed an endpoint that requires authentication, the block displays the required security scheme. This helps developers understand not just what the endpoint does, but how to access it.

The architecture documentation throughout this site embeds API endpoints where relevant, demonstrating how to integrate live specifications with explanatory content.

Next Steps