Embedding API Endpoints
Learn how to embed live API endpoint documentation directly in your architecture pages, keeping specifications in sync with explanatory content.
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
| Approach | When to Use |
|---|---|
| Embed endpoints | Explaining a specific API workflow in a guide |
| Embed endpoints | Documenting integration points with other systems |
| Embed endpoints | Providing context alongside architecture decisions |
| Embed endpoints | Creating a quick reference for commonly used endpoints |
| Link to full docs | Users need to browse all available endpoints |
| Link to full docs | The focus is on a full API reference |
| Link to full docs | Interactive testing (try it out) is needed |
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.