Microservice Specification: [service-name]
One-page-per-service canvas that records what a microservice is for,
who owns it, what it exposes and consumes, which data it owns, how it
runs, scales, is observed and secured, and how it is versioned. Based
on common industry practice for service canvases and service catalogue
entries. Replace every [bracketed] value and every row marked
Example. Worked examples use an inventory reservation service.
| Field | Value |
|---|
| Service name | [inventory-reservation] |
| Document version | [0.1] |
| Status | [Proposed / In development / Production / Deprecated] |
| Owning team | [@team-inventory] |
| Technical owner | [@tech-lead] |
| On-call rotation | [inventory-oncall] |
| Repository | [git URL] |
| Service tier | [Tier 1 / Tier 2 / Tier 3] |
| Last updated | YYYY-MM-DD |
1. Purpose and bounded context
1.1 Purpose
[One paragraph. Example: "Reserves stock for items in a checkout so that
two customers cannot buy the last unit, and releases reservations that
are not confirmed within 15 minutes."]
1.2 Bounded context
| Item | Value |
|---|
| Domain / subdomain | Example: Inventory / Availability (core subdomain) |
| Key domain terms | Example: Reservation, stock keeping unit (SKU), available-to-promise, hold expiry |
| Responsibilities | Create, confirm, release and expire reservations; publish availability changes |
| Not responsible for | Stock counts at warehouses (Warehouse service), prices (Pricing service), orders (Orders service) |
| Upstream contexts | Warehouse (stock levels), Catalogue (SKU validity) |
| Downstream contexts | Checkout, Orders, Storefront search |
2. Ownership and lifecycle
| Role | Name / channel |
|---|
| Owning team | [@team-inventory] |
| Product owner | [@product-owner] |
| On-call escalation | [Paging service], then [@engineering-manager] |
| Support channel | [#inventory-help] |
| Lifecycle stage | [Production since YYYY-MM-DD] |
| Planned changes | [Example: Multi-warehouse reservations in Q2] |
3. Interfaces
3.1 Exposed APIs
| API | Style | Contract | Consumers | Auth |
|---|
POST /v1/reservations | REST | [openapi.yaml#createReservation] | Checkout | OAuth 2.0 client credentials, scope inventory:reserve |
POST /v1/reservations/{id}/confirm | REST | [openapi.yaml] | Orders | Same, scope inventory:confirm |
DELETE /v1/reservations/{id} | REST | [openapi.yaml] | Checkout | Same |
GET /v1/availability?sku= | REST | [openapi.yaml] | Storefront, Search | Scope inventory:read |
| [API] | [REST / gRPC / GraphQL] | [Link] | [Consumers] | [Auth] |
3.2 Consumed APIs
| API | Provider | Purpose | Timeout | Fallback if unavailable |
|---|
GET /v2/skus/{sku} | Catalogue service | Validate SKU on reservation | 300 ms | Use cached SKU list (refreshed every 5 min) |
| [API] | [Provider] | [Purpose] | [Timeout] | [Fallback] |
4. Events
4.1 Published events
| Event | Channel | Schema | Trigger | Key |
|---|
| ReservationCreated | inventory.reservation.v1 | [registry subject] | Reservation stored | sku |
| ReservationExpired | inventory.reservation.v1 | [subject] | Hold timer elapsed | sku |
| AvailabilityChanged | inventory.availability.v1 | [subject] | Available quantity crosses a threshold | sku |
| [Event] | [Channel] | [Schema] | [Trigger] | [Key] |
4.2 Consumed events
| Event | Channel | Producer | Handling | Idempotency |
|---|
| StockAdjusted | warehouse.stock.v1 | Warehouse service | Update on-hand quantity | Event ID stored for 7 days |
| OrderCancelled | orders.order.v1 | Orders service | Release confirmed reservation | Reservation state check |
| [Event] | [Channel] | [Producer] | [Handling] | [Method] |
5. Data owned
| Data | Store | Classification | Retention | Shared how |
|---|
| Reservations | Example: PostgreSQL inventory_reservation | Internal | 90 days after expiry or confirmation | API and events only |
| Available-to-promise per SKU | Redis (derived, rebuildable) | Internal | Live | GET /availability |
| [Data] | [Store] | [Class] | [Retention] | [Mechanism] |
No other service reads these stores directly. Reporting uses the
published events.
6. Dependencies
| Dependency | Type | Criticality | Failure behaviour |
|---|
| PostgreSQL | Data store | Hard | Reservations fail with 503; checkout shows "try again" |
| Redis | Cache | Soft | Availability served from database at higher latency |
| Message broker | Messaging | Soft | Events buffered in outbox up to [6 hours] |
| Catalogue service | API | Soft | Cached SKU list |
| [Dependency] | [Type] | [Hard / Soft] | [Behaviour] |
7. Service level objectives
| SLI | SLO | Window | Measured at |
|---|
Availability of POST /reservations | 99.95% non-5xx | 28 days rolling | Gateway |
Latency of POST /reservations | 99% under 150 ms | 28 days rolling | Gateway |
| Expiry accuracy | 99.9% of holds released within 60 s of expiry | 28 days | Service metric |
| [SLI] | [SLO] | [Window] | [Point] |
Error budget for availability in a 28-day window:
B=(1−0.9995)×28×24×60≈20 minutes 8. Scaling and capacity
| Item | Value |
|---|
| Expected load | Example: 120 reservations/s average, 900/s at sale start |
| Scaling model | Horizontal; stateless pods; HPA on CPU 60% and request rate |
| Replicas | Min 3 (one per zone), max 30 |
| Known limit | Single hot SKU above 2 000 reservations/s contends on one row; mitigated with sharded counters |
| Load test | Last run YYYY-MM-DD at 1 500 reservations/s |
9. Configuration
| Key | Purpose | Default | Source |
|---|
HOLD_TTL_SECONDS | Reservation hold time | 900 | Environment |
MAX_QTY_PER_RESERVATION | Abuse limit per request | 20 | Feature flag service |
DB_URL | Database connection | none | Secrets manager inventory/db |
CATALOGUE_BASE_URL | Catalogue API | per environment | Environment |
| [KEY] | [Purpose] | [Default] | [Source] |
10. Deployment
| Item | Value |
|---|
| Runtime | Example: Container on Kubernetes, namespace inventory |
| Pipeline | [CI system] build, test, scan, sign, deploy to staging, canary 10% for 15 min, full rollout |
| Environments | dev, staging, production (two regions) |
| Rollback | Automatic on canary error rate above 1%; manual via [deploy tool] rollback |
| Database migrations | Expand and contract; run as a pre-deploy job |
| Release frequency | Daily |
11. Observability
| Signal | Where | Key items |
|---|
| Metrics | [Dashboard link] | Request rate, error rate, p99 latency, active holds, expiry lag |
| Logs | [Log query link] | Structured JSON; fields reservation_id, sku, trace_id |
| Traces | [Tracing link] | Spans for database, cache, catalogue calls |
| Alerts | [Alert rules link] | SLO burn rate (fast and slow), expiry lag above 120 s, outbox age above 5 min |
| Runbook | [Runbook link] | One section per alert |
12. Security
| Topic | Control |
|---|
| Inbound authentication | OAuth 2.0 tokens validated at gateway and service; mTLS in mesh |
| Authorisation | Scope per endpoint (3.1); reservations can only be confirmed by Orders |
| Outbound identity | Workload identity; no static credentials |
| Data | No personal data stored; reservation references checkout session ID only |
| Abuse | Per-session limit of [5] active reservations; quantity cap |
| Dependencies | Image and dependency scanning in CI; critical fixes within [7] days |
13. Versioning and compatibility
| Contract | Versioning | Compatibility promise | Deprecation notice |
|---|
| REST API | Major version in path (/v1) | Additive changes only within a major version | [6 months], Deprecation and Sunset headers |
| Events | Major version in channel name | Registry enforces backward-compatible schemas | [6 months] dual publishing |
| Service release | Semantic versioning of the build | n/a | Release notes in [link] |
14. Related documents
| Document | Link |
|---|
| REST API specification | [link] |
| Event API specification | [link] |
| Architecture decision records | [link] |
| Runbook | [link] |
| Threat model | [link] |
Standard and licence note
Based on common industry practice for microservice canvases and service
catalogue entries. Original text written for this collection; example
values are illustrative. Template licence: MIT.