Skip to content

API Design & OpenAPI Approach

Talisman projects are microservices, and each one publishes its own openapi.json contract through the OpenAPI Designer. This page describes the unified approach for designing, versioning, and exposing those REST APIs so that they stay consistent, independently deployable, and aligned with the microservice architecture described in Development & Deployment Principles.

URI and Naming Conventions

Root-Level Versioning

Always place the major version at the root of the API path. This establishes a clear, immutable contract for the entire endpoint structure and is the most widely adopted industry standard.

  • Standard: /v1/customers
  • Avoid: /customers/v1

Plural Resource Naming

Use plural nouns for all resources to maintain linguistic consistency across both collection and specific-entity operations.

  • Standard:
    • GET /v1/customers — retrieve a list of customers
    • GET /v1/customers/{id} — retrieve a specific customer
  • Avoid: /v1/customer

Microservice Boundaries

One Domain Per Service

Adhere strictly to Domain-Driven Design (DDD). In Talisman, 1 Project = 1 Deployment = 1 Service.

Each project should exclusively own a single domain namespace to ensure independent deployability, isolate failures, and prevent domain coupling.

  • The customer-v1 project exposes only /v1/customers/*
  • The order-v1 project exposes only /v1/orders/*

Avoid "God" Microservices

Do not group multiple distinct domains (e.g. /customers, /warehouse, and /orders) into a single Talisman project just to generate a single, monolithic openapi.json. This breaks the microservice paradigm and creates a deployment bottleneck.

Exception

Sub-resources inherently tied to a domain (e.g. /v1/orders/{id}/items) belong within the same service.

OpenAPI Aggregation

The OpenAPI Portal acts as an internal aggregator for your microservices. It dynamically fetches the individual openapi.json files from your deployed microservices (e.g. http://customer-v1:8080/openapi.json).

  • Best Practice: Rely on the Talisman Portal for internal developer discoverability, architectural oversight, and QA testing.
  • Do Not Manually Merge Specs: Never manually merge OpenAPIs in code. Let each service generate its own self-contained contract and let the Talisman Portal stitch the internal catalog together.

External Gateways

Because the Talisman OpenAPI Portal is an internal tool and not meant for external API consumers, your architecture must leverage an API Gateway for external traffic.

Gateway Federation

Consumers should never interact directly with individual microservice hostnames or ports (e.g. http://projectId:8080/v1). Instead, expose a unified base URL via an API Gateway (e.g. Kong, Apigee, AWS API Gateway). The Gateway handles path-based routing to the underlying Talisman projects:

graph LR
    Consumer(External Consumer)
    Gateway(API Gateway<br/>api.company.com)
    Customer(customer-v1:8080)
    Order(order-v1:8080)

    Consumer --> Gateway
    Gateway -- /v1/customers --> Customer
    Gateway -- /v1/orders --> Order
  • External request to https://api.company.com/v1/customers → Gateway routes to customer-v1:8080
  • External request to https://api.company.com/v1/orders → Gateway routes to order-v1:8080

External Developer Portals

For external consumers, configure your API Gateway or an external Developer Portal to ingest the individual openapi.json contracts from your Talisman services. The Gateway's portal will provide the unified, branded documentation necessary for external integration.