API / SERVICE DATA MODELLING

API / Service Data Modelling is the practice of designing the data contracts and structures that define how information is exchanged between services, applications, and systems. Rather than focusing on how data is stored internally, this approach concentrates on how data is exposed, requested, and consumed across interfaces.

The primary goal of API / Service Data Modelling is to ensure clarity, consistency, and stability in data exchanged across APIs and services. Well-designed API models reduce integration complexity, prevent misunderstandings between systems, and minimize runtime errors. They act as formal contracts between service providers and service consumers.

In this approach, the model defines the structure of inputs and outputs. For example, a Loan Application API may specify required request fields such as CustomerID, LoanAmount, and Term. The response may include fields such as LoanID, ApprovalStatus, and InterestRate. These definitions establish what data must be provided, what data will be returned, and under what rules. The emphasis is not on database tables but on message structures.

API data models are typically expressed using standards such as OpenAPI (Swagger) for REST services, GraphQL schemas for flexible querying, or WSDL for SOAP-based services. In microservices architectures, these contracts become essential to maintain decoupling between services.

In a loan approval ecosystem, a bank may expose several APIs. A customer mobile application calls an endpoint such as /loanApplications to submit an application. Back-office underwriting systems use /loanApprovals to process decisions. Regulatory authorities may consume /loanReports for compliance monitoring. Even if the bank’s internal storage shifts from relational databases to NoSQL or event-driven architectures, the API schema remains stable, ensuring consistent communication across stakeholders.

For example, a REST-based request might include CustomerID, LoanAmount, and OfficerID in a JSON payload. The response may return LoanID, Status, and nested details about the Officer and Customer. In a GraphQL model, a consumer could request only specific fields, such as LoanAmount, Status, and the names of the related Customer and Officer, avoiding unnecessary data transfer.

API / Service Data Modelling offers several strengths. It encapsulates data exchange contracts clearly. It is widely adopted across modern distributed systems, including REST, GraphQL, and gRPC architectures. It decouples internal database structures from external consumers, allowing backend evolution without breaking integrations.

However, challenges exist. REST APIs may suffer from over-fetching or under-fetching of data. Versioning and backward compatibility require careful governance. Poorly designed APIs can expose too much internal detail or insufficient context for consumers. Strong contract management and governance are therefore critical.

Normalization forms do not apply to API modelling because the focus is not relational storage but message exchange. Canonical representations often matter more than normalized schemas. The key concern is whether systems agree on the structure and meaning of exchanged data.

API / Service Data Modelling defines how data is shared rather than how it is stored. In loan approval systems, it enables seamless integration between mobile apps, underwriting services, payment platforms, and regulators. It ensures that every participant speaks the same data language, regardless of internal architectural differences.

In modern distributed enterprises, APIs are often the primary interface through which systems interact. Designing their data models carefully is therefore as important as designing the underlying databases themselves.

Loan Approval Example (REST JSON)

Request:

POST /loanApplications

{

"CustomerID": "C101",

"LoanAmount": 50000,

"OfficerID": "O11"

}

Response:

{

"LoanID": "L001",

"Status": "Approved",

"Officer": {"OfficerID": "O11", "Name": "Ahmed Raza"},

"Customer": {"CustomerID": "C101", "Name": "Ali Khan"}

}

GraphQL Example

query {

loan(id: "L001") {

LoanAmount

Status

Customer { Name }

Officer { Name }

}}

Object-Oriented vs API / Service Data Modelling

“OODM looks like API modelling, because all three represent entities as rich, nested objects. The difference is that OODM bundled logic with data inside the database, while APIs separate storage from application logic.”

What OODM resembles

OODM looks very much like API / Service Data Modelling (especially JSON payloads). Here’s why:

API / Service Data Modelling (REST/GraphQL)

• APIs send and receive object-like structures (JSON, XML).
• These payloads are essentially “objects on the wire.”
• An OODM LoanApplication object would map almost 1:1 to an API response body:

{

"LoanID": "L001",

"Customer": {"CustomerID": "C101", "Name": "Ali Khan"},

"Officer": {"OfficerID": "O11", "Name": "Ahmed Raza"},

"Status": "Approved"

}

Why they’re not the same

• OODM: Tried to make the database itself object-oriented (data + methods stored together).
• APIs: Keep only the data representation; logic lives in application code or services.