Part 042 — REST Contracts, Resource Semantics, Domain Translation, and TM Forum Alignment

Positioning

API contract bukan sekadar JSON schema.

Contract menentukan:

• resource identity;
• business semantics;
• lifecycle;
• command behavior;
• idempotency;
• concurrency;
• errors;
• versioning;
• security;
• pagination;
• and compatibility.

Dalam telecom/enterprise ecosystem, TM Forum Open APIs dan vocabulary dapat menjadi useful published language.

Namun mapping yang buruk dapat menghasilkan:

• internal model dipaksa mengikuti external schema secara literal;
• field semantics tidak cocok;
• action dan lifecycle ambigu;
• extension tidak terkontrol;
• dan consumers bergantung pada internal implementation detail.

Core thesis: gunakan API contract sebagai stable boundary dan anti-corruption layer. TM Forum mapping harus semantic, versioned, dan traceable—bukan one-to-one field copy. Internal aggregate tetap dimiliki bounded context; external API adalah published language.

1. API Contract

API Contract mencakup:

• request/response schema;
• operation semantics;
• lifecycle;
• errors;
• headers;
• versioning;
• authentication;
• authorization;
• consistency;
• and service expectations.

2. Contract versus Implementation

Contract describes observable behavior.

Implementation may change while contract remains compatible.

3. Contract versus Domain Model

External contract should not expose every internal class/table.

4. Published Language

An API schema can serve as shared integration language.

5. Anti-Corruption Layer

Maps:

• external resource;
• to internal command/query;
• and internal result/event back to external representation.

6. API Styles

Possible styles:

• REST;
• RPC;
• gRPC;
• GraphQL;
• event/message;
• file/batch;
• and asynchronous operation API.

7. REST Resource

A resource has:

• stable identity;
• representation;
• lifecycle;
• and related operations.

8. Command Endpoint

Some domain actions are better modeled explicitly.

Examples:

POST /quotes/{id}/submit
POST /offers/{id}/accept
POST /productOrders/{id}/cancel

9. Resource Mutation versus Command

Use generic CRUD only when semantics truly are CRUD-like.

10. Query API

Retrieves resource/projection without state change.

11. Command API

Expresses business intent and enforces guards.

12. Async Operation API

Useful for:

• pricing;
• proposal rendering;
• Order creation;
• decomposition;
• cancellation;
• and Billing activation.

13. Resource Identity

Use opaque stable ID.

14. Business Identifier

Can coexist with technical ID.

15. href

A canonical resource URL may be included.

16. Resource Type

Polymorphic APIs may include type discriminator.

17. Schema Version

Contract version should be explicit in governance, not necessarily payload field for every API.

18. HTTP Method Semantics

GET

Read resource or collection.

Expected safe and idempotent.

POST

Create resource or invoke non-idempotent/business command.

Can be made idempotent using key.

PUT

Replace/update resource at known URI with idempotent semantics.

PATCH

Partial modification.

Requires carefully defined patch semantics.

DELETE

Request deletion/cancellation/termination depending resource semantics.

Business resources often should use explicit command rather than physical delete.

19. Safe Operation

No intended state change.

20. Idempotent Operation

Repeated same logical request yields no additional effect.

21. POST Idempotency

Use:

Idempotency-Key: opaque-key

where creation/action side effects are high-value.

22. Expected Version

Use optimistic concurrency.

23. ETag

Response can include:

ETag: "v17"

24. If-Match

Client sends expected version:

If-Match: "v17"

25. Precondition Failure

Return appropriate concurrency error when version differs.

26. Conditional GET

Use If-None-Match and 304 Not Modified where useful.

27. Resource Creation

Typical response:

• 201 Created;
• Location;
• representation/reference.

28. Async Acceptance

Typical response:

• 202 Accepted;
• operation resource;
• status URL.

29. Validation Error

Usually 400 Bad Request or domain-specific equivalent.

30. Unauthorized

401 when authentication missing/invalid.

31. Forbidden

403 when authenticated but not allowed.

32. Not Found

404 for absent or intentionally undisclosed resource.

33. Conflict

409 for domain conflict/idempotency conflict/current-state mismatch.

34. Precondition Failed

412 for failed If-Match.

35. Unprocessable Content

422 may represent semantic validation failure where API governance permits.

36. Too Many Requests

429 with retry guidance.

37. Service Unavailable

503 for temporary dependency/service unavailability.

38. Gateway Timeout

504 at gateway boundary.

Does not prove downstream failure.

39. Error Contract

A structured error should include:

code
reason
message
status
referenceError
@type
details
field/path
correlationId

Exact fields depend on governance.

40. Stable Error Code

Machine-readable and versioned.

41. Human Message

Useful for users/operators, not primary program logic.

42. Error Detail

Can include multiple validation issues.

43. Sensitive Error Data

Avoid leaking:

• internal stack;
• SQL;
• cost/margin;
• security policy;
• and cross-tenant existence.

44. Correlation ID

Return/propagate for support.

45. Pagination

Collection endpoints should define:

• offset/limit;
• page/pageSize;
• cursor;
• or continuation token.

46. Cursor Pagination

Prefer for changing/large datasets.

47. Stable Sort

Pagination requires deterministic order.

48. Default Page Size

Set and document.

49. Maximum Page Size

Protect service.

50. Total Count

May be expensive.

Make optional or approximate if needed.

51. Filtering

Use documented fields/operators.

52. Sorting

Allow only stable indexed fields where practical.

53. Field Selection

Partial response can reduce payload.

54. Expansion

Explicitly include related resources.

Avoid uncontrolled deep expansion.

55. Search

Complex search may use dedicated endpoint/query language.

56. Bulk API

Useful for:

• qualification;
• validation;
• product updates;
• and reconciliation.

Preserve per-item identity/result.

57. Partial Bulk Success

Return per-item outcome.

58. Bulk Idempotency

Use batch and item keys.

59. API Versioning

Possible:

• URI;
• header;
• media type;
• or contract evolution without explicit version path.

60. Compatibility First

Prefer additive compatible changes.

61. Breaking Changes

Examples:

• remove field;
• change meaning;
• change requiredness;
• change enum behavior;
• and change lifecycle.

62. Additive Field

Usually compatible if consumers tolerate unknown fields.

63. New Enum Value

Often breaks strict consumers.

Treat carefully.

64. Optional to Required

Breaking for producers.

65. Required to Optional

Can break consumers assuming presence.

66. Numeric Precision Change

Potentially breaking.

67. Semantic Change

Breaking even if schema unchanged.

68. Deprecation

Mark:

• field/operation;
• replacement;
• date;
• and migration guide.

69. Sunset

Communicate removal date and policy.

70. Consumer Registry

Know who uses contract.

71. Contract Compatibility Matrix

Track provider/consumer versions.

72. Contract Test

Provider and consumer expectations validated automatically.

73. Schema Linting

Enforce:

• naming;
• descriptions;
• required metadata;
• error model;
• security;
• and pagination.

74. OpenAPI

Useful for synchronous HTTP contract documentation/generation.

75. AsyncAPI

Useful for event/message contract documentation.

76. Protobuf/gRPC

Useful for typed RPC/internal high-throughput contracts.

77. Generated Client

Can reduce manual errors.

78. Generated Server Stub

Useful starting point, not domain implementation.

79. Generation Risk

Generated models can leak transport types into domain.

Use mapping layer.

80. API-First

Design and review contract before implementation.

81. Code-First

Can be efficient but risks accidental contract exposure.

82. Contract Governance

Review:

• semantic owner;
• security;
• compatibility;
• naming;
• lifecycle;
• and operational impact.

83. TM Forum

TM Forum provides industry vocabulary and Open API patterns for telecom business processes.

Use current official specifications as source when implementing exact versions.

84. TM Forum Mapping Principle

Map by semantic role, not field-name similarity.

85. Internal Model Independence

Internal aggregates need not match TM Forum payload structure.

86. External Compatibility Layer

Use adapter/ACL between internal domain and TM Forum API.

87. Candidate TM Forum Domains

Commonly relevant conceptual areas include:

• Product Catalog;
• Product Offering Qualification;
• Quote;
• Product Order;
• Product Inventory;
• Service Order;
• Resource Order;
• Agreement;
• Party/Customer/Account;
• Billing Account;
• and Trouble/Problem domains.

Exact API names and versions must be verified against official TM Forum sources.

88. Product Catalog Mapping

Internal concepts may map to:

• Product Offering;
• Product Specification;
• Product Offering Price;
• characteristic definitions;
• relationships;
• lifecycle status.

89. Product Offering

Commercially available package or sellable option.

90. Product Specification

Definition of Product structure/capabilities.

91. Product Offering Price

Commercial price definition associated with offering.

92. Catalog Mapping Caveat

Internal catalog may contain richer:

• inheritance;
• rules;
• constraints;
• and tenant variation

than external API.

93. Qualification Mapping

Internal qualification result may map to Product Offering Qualification concepts.

94. Qualification Item

Represents candidate offering/site/account assessment.

95. Qualification Result

Possible external status/eligibility reason mapping.

96. Qualification Evidence

May remain internal reference rather than exposing full evidence.

97. Quote Mapping

Internal Quote can map to external Quote resource.

98. Quote Identity Mapping

Preserve:

• internal ID;
• external ID;
• version/revision;
• and href.

99. Quote Item Mapping

Map item identity, action, Product Offering, Product configuration, quantity, price, and relationships.

100. Quote State Mapping

Internal detailed states may map to a smaller external state vocabulary.

101. Lossy State Mapping

When external states are coarser, retain internal state and document projection.

102. Quote Price Mapping

Map:

• one-time;
• recurring;
• usage;
• tax;
• and discount components.

103. Quote Revision Mapping

External API may not represent internal revision semantics exactly.

Use extension/reference or separate version field per governance.

104. Quote Acceptance Mapping

Acceptance may be explicit command/internal event even if external resource uses state transition.

105. Product Order Mapping

Internal Product Order maps to external Product Order resource.

106. Product Order Item Mapping

Map:

• ID;
• action;
• Product;
• offering/specification;
• quantity;
• requested dates;
• relationships;
• and state.

107. Action Mapping

Internal vocabulary may include:

• ADD;
• MODIFY;
• DELETE;
• SUSPEND;
• RESUME;
• REPLACE;
• RENEW.

External vocabulary may differ.

Use mapping table.

108. Product Order State Mapping

Internal Order and Item states can be richer than external states.

109. Item State Projection

Document aggregation and projection semantics.

110. Product Inventory Mapping

Internal Product maps to external Product resource.

111. Product Identity Mapping

Preserve stable installed Product ID and external references.

112. Product Characteristic Mapping

Map value, unit, name/reference, and type.

113. Product Relationship Mapping

Map contains, dependsOn, replaces, bundledWith, and other relationships.

114. Product Lifecycle Mapping

Map active/suspended/terminated/etc. carefully.

115. Pending Actions

External Product representation may need extension or related Order query.

116. Service Order Mapping

Fulfillment Service Order/Items map to service-order concepts.

117. Resource Order Mapping

Resource provisioning maps to resource-order concepts.

118. Product-to-Service Lineage

Expose references where contract permits.

119. Service-to-Resource Lineage

May remain internal or be exposed via related entities.

120. Agreement Mapping

Internal Agreement maps to external Agreement resource/concepts.

121. Agreement Item Mapping

Map products, terms, parties, effective period, and references.

122. Agreement Amendment Mapping

May require version/relationship extension if not directly represented.

123. Party Mapping

Map:

• Individual;
• Organization;
• RelatedParty;
• role;
• and contact medium.

124. Customer Account Mapping

Customer/account semantics may differ by implementation.

125. Billing Account Mapping

Map financial account identity and related parties.

126. Geographic Address/Site Mapping

Use stable geographic/site references where available.

127. External Reference

TM Forum-style payloads commonly support external reference concepts.

Use typed references.

128. Related Entity

Represent links to other domain resources.

129. Polymorphism Metadata

Fields such as:

• @type;
• @baseType;
• @schemaLocation

may appear in TM Forum-style APIs.

Exact use should follow official API specification and organizational governance.

130. Extension Mechanism

Use controlled extension for internal fields not represented externally.

131. Extension Namespace

Avoid collisions and ambiguous generic fields.

132. Extension Governance

Every extension should have:

• owner;
• schema;
• purpose;
• compatibility;
• and retirement plan.

133. Extension Smell

Most payload in vendor-specific extension means standard mapping is weak or wrong API selected.

134. Characteristic as Escape Hatch

Do not place every unrelated field into generic characteristic list.

135. RelatedParty as Escape Hatch

Use meaningful role taxonomy.

136. Note as Escape Hatch

Free-text notes should not carry machine-required semantics.

137. State Mapping Table

Example structure:

Actual state vocabularies must be verified.

138. Action Mapping Table

139. Price Mapping Table

Exact API structure must be confirmed.

140. Reference Mapping

Every reference should include enough identity:

• ID;
• href;
• name;
• type;
• and external reference where needed.

141. Reference Snapshot

Name can be snapshot for display; ID remains authority.

142. Circular Expansion

Avoid deep embedded recursion.

Use references and controlled expansion.

143. Resource Representation

Separate:

• summary;
• detail;
• and event payload.

144. Event Representation

Event should not always include full resource.

145. Event Header

Useful fields:

eventId
eventTime
eventType
correlationId
domain
title
priority

Exact schema follows governance.

146. Event Payload

Contains resource reference or selected changed fields.

147. Event Ordering

Include aggregate/resource version.

148. Event Idempotency

Consumers deduplicate by event/logical identity.

149. Event Subscription

Define:

• filter;
• callback/topic;
• security;
• retry;
• and dead-letter behavior.

150. Callback API

Consumer endpoint should authenticate and deduplicate.

151. TM Forum Event Mapping

If exposing TM Forum-style events, map internal integration events to external event resources through adapter.

152. Internal Event Independence

Do not force internal event sourcing schema to equal public event schema.

153. API Commands for State Change

External standards may represent state update through PATCH.

Internal adapter should convert to explicit domain command.

154. PATCH Semantics

Options:

• JSON Merge Patch;
• JSON Patch;
• custom partial object.

Pick one and document.

155. PATCH Guard

Only allowed fields and transitions.

156. Immutable Fields

Reject modification to:

• identity;
• accepted revision;
• source lineage;
• and immutable history.

157. State Transition via PATCH Risk

A client setting state=completed can bypass evidence.

Prefer command endpoint or enforce full domain transition.

158. Delete Semantics

For business resources, DELETE may mean:

• remove draft;
• cancel;
• deactivate;
• or unsupported.

Document explicitly.

159. Query Consistency

Document whether GET returns:

• authoritative current state;
• eventual projection;
• or snapshot.

160. Read Model Lag

Expose lastUpdated/version if useful.

161. Cache-Control

Use carefully for customer-specific resources.

162. ETag

Supports cache and concurrency.

163. Sensitive Resource Caching

Prevent shared/proxy caching where unsafe.

164. Content Negotiation

Support media types/versions if governance requires.

165. Compression

Useful for large payloads.

166. CORS

Only relevant for browser clients and must be governed.

167. Authentication

Possible:

• OAuth2/OIDC;
• mTLS;
• service identity;
• signed webhook;
• API key for limited cases.

168. Authorization

Use:

• resource ownership;
• tenant;
• role;
• scope;
• party/account relation;
• and field-level rules.

169. OAuth Scope

Scopes should express capability.

170. Tenant Context

Do not trust tenant ID from payload alone.

Derive/validate against authenticated identity.

171. Object-Level Authorization

Every resource ID lookup must enforce tenant and permission.

172. Field-Level Authorization

Price, cost, margin, approval, and legal fields may differ.

173. Data Minimization

Public API returns only required fields.

174. PII

Protect party/contact/address data.

175. Security Logging

Log decisions and correlation without sensitive payloads.

176. Rate Limiting

Apply by:

• client;
• tenant;
• operation;
• and resource intensity.

177. Quota

Long-term usage limits differ from short-term rate limits.

178. Backpressure

Async APIs should expose queue/operation state.

179. Load Shedding

Reject optional/expensive work under overload.

180. Retry Guidance

Return retryable status and Retry-After where appropriate.

181. API Timeout

A caller timeout does not prove command failure.

182. Operation Lookup

Provide status lookup by operation/idempotency key.

183. Request Size Limit

Important for large Quote/Order payloads.

184. Large Resource

Use:

• item subresources;
• pagination;
• async import;
• or bulk file.

185. Streaming

May be useful for exports or large results.

186. Batch Import

Needs schema/version, per-row errors, idempotency, and reconciliation.

187. Partial Response

Reduce payload while preserving required identity/version.

188. API SLI

Examples:

• availability;
• latency;
• error rate;
• and correctness.

189. Business SLI

Examples:

• duplicate Order rate;
• accepted Quote conversion success;
• and stale Inventory conflict rate.

190. Contract SLI

• compatibility violations;
• deprecated usage;
• and consumer test failure.

191. Observability

Trace:

• client;
• operation;
• resource;
• idempotency;
• correlation;
• and downstream context.

192. Semantic Logging

Log business command/outcome rather than raw payload only.

193. API Metrics

• operation rate;
• latency;
• error code;
• response size;
• and pagination behavior.

194. Consumer Metrics

Track client/version usage.

195. Deprecation Metrics

Measure remaining calls to deprecated field/operation.

196. Schema Registry

For events and possibly APIs.

197. Contract Catalog

Store:

• owner;
• version;
• lifecycle;
• consumers;
• SLO;
• and docs.

198. API Linting Rules

Examples:

• IDs are strings;
• dates use ISO format with timezone where needed;
• Money includes currency;
• pagination standard;
• errors standardized;
• and commands require idempotency.

199. Semantic Review

Lint cannot detect meaning conflicts.

Human/domain review remains.

200. Compatibility Automation

Diff schemas and classify breaking changes.

201. Consumer-Driven Contract Testing

Consumers publish expectations.

202. Provider Verification

Provider CI validates expectations.

203. Generated Client Compatibility

Regenerate and compile representative consumers.

204. Contract Test Data

Use realistic:

• hierarchy;
• prices;
• actions;
• states;
• and extensions.

205. Golden Payload

Versioned representative payload for regression.

206. Round-Trip Mapping Test

Internal -> external -> internal should preserve intended semantics where mapping is lossless.

207. Lossy Mapping Test

Document exactly what is lost.

208. State Mapping Test

Every internal state maps or fails explicitly.

209. Enum Evolution Test

Consumers tolerate new values or use fallback strategy.

210. Pagination Test

Stable results under concurrent inserts/updates.

211. Idempotency Test

Same command/key returns same outcome.

212. Concurrency Test

Stale ETag is rejected.

213. Security Test

Cross-tenant access and field leakage.

214. Performance Test

Large Quote/Order and nested relationships.

215. API Gateway

Can provide:

• authentication;
• routing;
• rate limit;
• observability;
• and policy enforcement.

216. Gateway Anti-Pattern

Do not put domain state transitions or mapping logic in gateway.

217. Service Mesh

Can provide mTLS, telemetry, and traffic control.

218. Mesh Anti-Pattern

Retries at mesh plus application plus workflow can multiply.

219. BFF

Adapts APIs for UI/channel.

220. BFF and TM Forum

External standardized API may differ from internal UI BFF needs.

221. Partner API

May expose stable TM Forum-aligned contract with stricter security and lifecycle.

222. Internal API

Can be more specialized but should still be governed.

223. Legacy Adapter

Maps file/SOAP/proprietary API to internal commands.

224. Migration Adapter

Supports old and new contract during transition.

225. Version Translation

Adapter can translate older payload to current internal command.

226. Dual API Version

Avoid indefinite support.

Set deprecation and migration plan.

227. Canonical API Team Risk

One central team owning every domain API becomes bottleneck.

Domain context should own semantics.

228. API Platform Role

Provide:

• standards;
• tooling;
• linting;
• gateway;
• schema registry;
• and generated clients.

229. Domain Team Role

Own:

• resource semantics;
• lifecycle;
• errors;
• compatibility;
• and operations.

230. TM Forum Conformance

Exact conformance requires validating against relevant official specification, schema, and test requirements.

Do not claim conformance based only on similar field names.

231. Conformance Dimensions

Possible:

• resource shape;
• mandatory fields;
• operations;
• events;
• behavior;
• and test suite.

232. Partial Alignment

An API may be TM Forum-inspired/aligned without full conformance.

State this honestly.

233. Vendor Extensions

Can coexist with alignment if governed.

234. Extension Compatibility

Consumers should ignore unknown extensions unless explicitly required.

235. Standard Version Pinning

Record exact external standard/API version used by implementation.

236. Standard Upgrade

Requires:

• schema diff;
• semantic diff;
• adapter changes;
• consumer testing;
• and migration.

237. Internal Independence during Upgrade

ACL allows external version upgrade without rewriting internal aggregates.

238. Mapping Registry

Store mappings by:

• internal version;
• external API/version;
• resource type;
• and direction.

239. Mapping Owner

Domain/API team owns mapping semantics.

240. Mapping Documentation

For each field:

• internal source;
• external target;
• conversion;
• loss;
• and extension.

241. Field Mapping Template

Internal field:
External field:
Direction:
Transformation:
Requiredness:
Authority:
Lossy:
Default:
Version:

242. Resource Mapping Template

## Internal Aggregate / Projection

## External Resource

## Identity Mapping

## Lifecycle Mapping

## Field Mapping

## Relationship Mapping

## Price / Money Mapping

## Action Mapping

## Error Mapping

## Extensions

## Lossy Semantics

## Version / Conformance

## Tests

243. API Contract Template

## Purpose / Owner

## Resource / Command

## Identity / URI

## Methods / Semantics

## Request / Response

## Headers

## Idempotency

## Concurrency / ETag

## Errors

## Pagination / Filtering / Sorting

## Security / Tenant

## Consistency / Freshness

## Events / Async Operations

## Versioning / Deprecation

## SLIs / Runbooks

244. Error Mapping Template

Internal reason:
External status:
External error code:
Message:
Retryable:
Field/path:
Security redaction:

245. State Mapping Template

Internal state:
External state:
Substate/extension:
Loss:
Allowed commands:
Terminal:

246. Event Contract Template

## Event Identity / Type

## Producer / Owner

## Trigger

## Resource / Aggregate Version

## Payload / References

## Ordering Key

## Idempotency

## Security

## Delivery / Retry

## Schema Evolution

## Consumers

247. Compatibility Matrix Template

248. API Invariants

Representative:

• resource identity is stable;
• business commands enforce domain guards;
• same idempotency key and payload yields one outcome;
• stale ETag cannot overwrite newer state;
• external state cannot force invalid internal transition;
• Money always includes currency;
• every reference is tenant-authorized;
• and external mapping does not overwrite internal semantic authority.

249. Worked Example: Quote Create

External request creates Quote draft.

Adapter:

• authenticates tenant;
• validates parties/catalog references;
• creates internal command;
• stores external ID/reference;
• returns 201 Created.

250. Worked Example: Quote Repricing

Repricing is async.

API:

• POST /quotes/{id}/reprice;
• idempotency key;
• returns operation;
• final Quote references immutable Price Snapshot.

251. Worked Example: Offer Acceptance

Do not accept by generic state PATCH.

Use explicit command with:

• Offer/Proposal identity;
• expected version;
• accepter evidence;
• and idempotency key.

External adapter maps outcome to resource state/event.

252. Worked Example: Product Order Create

One accepted Quote creates multiple Product Orders.

API returns operation containing generated Order references.

253. Worked Example: Product Modify

Request references:

• installed Product ID;
• Product version/ETag;
• target characteristics;
• and action.

Stale version returns conflict.

254. Worked Example: TM Forum Quote State Projection

Internal states:

• CONFIGURING;
• PRICING_PENDING;
• APPROVAL_PENDING;
• PRESENTED.

External vocabulary has fewer states.

Adapter maps coarse state plus optional governed substate extension.

255. Worked Example: Price Mapping

Internal Price Snapshot contains:

• one-time;
• recurring;
• usage;
• discounts;
• and tax estimate.

Adapter maps external price components while preserving accepted charge IDs as extensions/external references.

256. Worked Example: Replace Action

Internal REPLACE maps to external action representation plus:

• source Product reference;
• target Product;
• replacement relationship.

Do not flatten into generic modify without lineage.

257. Worked Example: Large Order

10,000 items.

Use:

• async import/create;
• item pagination;
• operation resource;
• and per-item validation results.

Avoid one unbounded synchronous payload.

258. Worked Example: Same Key Different Payload

Client retries Order creation with same key but changed requested date.

Return conflict, not reused success.

259. Worked Example: Callback Event

External consumer receives Product Order state event twice.

Event ID/resource version allows deduplication.

260. Worked Example: Extension Governance

Internal approvalEvidenceRef is not in standard schema.

Extension:

• namespaced;
• documented;
• optional;
• owner assigned;
• and tested.

261. Worked Example: Standard Upgrade

External API moves to newer official version.

ACL supports both external versions while internal Order aggregate remains unchanged.

262. Worked Example: Consumer Breakage

Provider adds enum value.

Strict generated consumer fails.

Compatibility policy introduces unknown fallback and contract test.

263. Worked Example: Cross-Tenant Access

Caller supplies Product ID from another tenant.

Resource lookup enforces tenant scope and returns non-disclosing error.

264. Worked Example: Timeout

Create Order request times out.

Client queries operation/idempotency key.

Existing result is returned.

265. Senior Engineer Operating Model

Treat contract as behavior

Not just schema.

Keep domain model internal

Use adapters and published language.

Prefer explicit commands

For business transitions.

Make idempotency and concurrency standard

Especially create/accept/cancel.

Map TM Forum semantically

Document lossy mappings and extensions.

Version mappings and external standards

Do not rely on “latest”.

Automate compatibility

Lint, diff, contract tests, generated clients.

Protect tenant and field boundaries

Every reference and response.

Operate APIs

Consumer registry, metrics, deprecation, and runbooks.

266. Internal Verification Checklist

Contract ownership

• Siapa owner API Quote, Order, Product, Agreement, and Billing?
• Are domain teams accountable for semantics and compatibility?
• Is an API catalog/consumer registry maintained?
• Are runbooks and SLIs defined?

HTTP/API semantics

• Which operations are resource CRUD versus explicit commands?
• How are idempotency keys scoped?
• Are ETag/If-Match used?
• What async operation pattern exists?

Errors and collections

• Is error taxonomy stable?
• Are retryability and field-level issues represented?
• Are pagination, filtering, sorting, expansion, and partial response standardized?
• Are large resources handled safely?

TM Forum mapping

• API mana yang memakai TM Forum?
• What exact official API/version is implemented?
• Is mapping semantic rather than field-copy?
• Are state/action/price/relationship mappings documented?

Extensions and conformance

• Which vendor/customer extensions exist?
• Are namespaces, owners, and compatibility rules defined?
• Is the API fully conformant, aligned, or merely inspired?
• Are conformance claims tested against official artifacts?

Security

• How are authentication, scopes, tenant context, object authorization, and field security enforced?
• Are PII and financial fields minimized?
• Are callbacks signed and replay-protected?
• Are cross-tenant IDs handled safely?

Compatibility and tooling

• Are OpenAPI/AsyncAPI/protobuf contracts versioned?
• Are schema linting and breaking-change detection automated?
• Are consumer-driven contract tests used?
• Do generated clients tolerate enum evolution?

Operations

• Are rate limits, deadlines, retries, and load shedding defined?
• Can timeout outcomes be queried?
• Are deprecated consumers measurable?
• What incidents reveal semantic contract mismatches?

267. Practical Exercises

Exercise 1 — API command inventory

Classify operations as query, resource mutation, command, or async operation.

Exercise 2 — TM Forum mapping

Map Quote, Product Order, Product Inventory, Agreement, and Party resources.

Exercise 3 — State/action mapping

Document lossy states and action extensions.

Exercise 4 — Compatibility

Evaluate 30 schema changes as compatible or breaking.

Exercise 5 — Contract tests

Create provider/consumer tests for idempotency, ETag, enum evolution, and pagination.

Exercise 6 — Security

Threat-model cross-tenant reference, webhook replay, and field leakage.

268. Part Completion Checklist

You are done if you can:

• define API contract beyond schema;
• choose resource versus command semantics;
• standardize idempotency, concurrency, errors, and async operations;
• version and deprecate contracts safely;
• map internal contexts to TM Forum vocabulary semantically;
• document state/action/price/relationship translations;
• govern extensions and conformance claims;
• automate linting, compatibility, and contract testing;
• enforce tenant/object/field security;
• and create an internal API/TM Forum verification backlog.

269. Key Takeaways

1. API contract defines behavior, not only JSON shape.
2. External API should not expose internal aggregate directly.
3. Explicit commands protect business transitions.
4. Idempotency and ETag are core correctness controls.
5. TM Forum mapping must be semantic and versioned.
6. State and action mappings may be lossy and must be documented.
7. Extensions need governance.
8. Conformance requires official-version validation and tests.
9. Contract compatibility must be automated and observed.
10. Internal CSG APIs and TM Forum usage must be verified.

270. References

Conceptual baseline:

• HTTP method, status code, caching, conditional request, and content-negotiation semantics.
• OpenAPI, AsyncAPI, protobuf/gRPC, API linting, generated clients, and contract-testing practices.
• Domain-Driven Design anti-corruption layers, published languages, bounded contexts, commands, and projections.
• TM Forum conceptual domains and Open API patterns for Product Catalog, Qualification, Quote, Product Order, Product Inventory, Service/Resource Order, Agreement, Party, and Billing Account.
• Distributed systems idempotency, optimistic concurrency, async operations, retries, and event delivery.

Exact TM Forum API names, schema details, and versions should be verified against official TM Forum specifications used by the organization. These references do not define internal CSG API contracts or conformance status.