Skip to content

SaaS Solution Platform — API Contract Specification

Purpose

Define how public APIs are exposed for SaaS bounded-context services so gateways, shell, MFEs, and peers depend on stable, versioned packages.

Package Naming

Pattern Example
ServiceModel ConnectSoft.Saas.<Context>.ServiceModel
REST API (optional split) ConnectSoft.Saas.<Context>.RestApi
gRPC (optional) ConnectSoft.Saas.<Context>.Grpc

Context uses the bounded-context short name (e.g. ProductsCatalog, Tenants).

Versioning

  • Semantic versioning for all NuGet contracts.
  • Breaking HTTP path, DTO shape, or gRPC proto changes → major bump.
  • Additive fields/endpoints → minor bump.
  • Consumers (shell, MFEs, gateway) pin upper bound compatible ranges.

REST Conventions

  • OpenAPI per service; error model with traceId, errorCode, localized message where applicable.
  • Tenant scope — Prefer claims + header propagation patterns documented in ConnectSoft Documentation (guides/saas).

gRPC (Optional)

  • Proto packages versioned with ServiceModel major alignment.
  • Gateway may expose REST only to browsers; gRPC for service-to-service.

Forbidden

  • No public references to Application or Domain assemblies from consumers.
  • No leaking ORM entities into ServiceModel DTOs.