Data Models for API's are NOT Canonical or Domain Models, they are your User Model.
After 2 years, I have decided to start blogging again. I have no reason for this new motivation to write. The New focus of the Blog will be centered around Mobile, API's, and Platform as a Service.
When starting development for a Modern Web or Mobile Application, one key aspect to address is how to generate JSON from backend data sources. For many, JSON is just a view or format of back end data. For simple applications with one database, dedicated to that single application, exposing back end artifacts may be simple. However, things have evolved and the world is now speaking APIs. It is no longer as simple as saying expose data as JSON.
Enterprise back ends have grown more complex. The larger the enterprise, the better the possibility that you have to fetch data from a shared back end. This leads developers to develop an application Domain Model that represents the business view of the application. When an application will have to access multiple back ends then a Domain Model typically referred to as a Canonical Data Model, which represents the data model for an enterprise and maintains relationships to different back end systems.
The issue is that exposing your canonical or domain data directly as JSON will make it difficult for front-end developers and API consumers. Back end domains tend to be very rich and contain many details and relationships that may not be needed by end users. Therefore, when building enterprise systems, taking your back end data and exposing it can lead to very poor Web APIs.
You see, when building Modern Applications, your REST APIs can end up becoming the foundations for public Web APIs. REST design for these systems should be focused around creating a specific data model for the Consumer that we like to call the User Model. This is the view of the data that is meaningful to the end user. This model does not have to be bound to a single web view, but can be shared across all devices and browsers where the user accesses the data.
The foundation of Web API's is the Consumer's Data Model, and when designing Web API's, you must design the data around "How the user see's the data." What is a Bank User's view of his account, how does an insurance customer see his or her policy? You should be able to define your API's as a headless business.
Back end data models define a different data model (canonical or domain), they define how a provider view's the data. It usually drives how a company might monitor a customer, how a policy flows from customer to agent, and so forth. Both are important but fundamentally different data models. The figure below highlights the difference:
Back end data models define a different data model (canonical or domain), they define how a provider view's the data. It usually drives how a company might monitor a customer, how a policy flows from customer to agent, and so forth. Both are important but fundamentally different data models. The figure below highlights the difference:
User Models are usually flatter and channel constraint. Besides understandable data, it may also be aware of through what channel a user views the data. Implementations may account for things like slower mobile networks through paging. Both the structure and data tend to be updated more frequently through interactive conditions. They form the foundation of data for "systems of engagement." By contrast, Canonical data models are usually rich data models, with rich relationships. They tend to be the main record of the provider and are driven by key transactions. They are the data models for systems of record.
API's should then be designed around the consumer's view of the data. The initial design for the data can come out initial designs for a particular UI, and should evolve from there as users use different channels to access that data. A user flow using different channels may modify the data. For example, I might start a claim at the sight of an accident with my mobile phone. I might later complete the data entry behind a laptop. I might check the status on my tablet. An API's central source of design is the User's viiew of the world.
End user's do not always understand their requirements in the beginning. User needs change over time sometimes. As you are building new apps, you may need to put yourself in the user's shoes and imagine where they need to go. Therefore, API design should facilitate building the Minimum Viable Product (https://mushi387.wordpress.com/tag/build-measure-learn/). Meaning the consumer model might initially start small and grow over time as Agile methods add more requirements. That is why dynamic formats like JSON are more appealing.
In general, it is time to view your API's as your end user's view of the data. It is time to start designing these models as they will serve the foundation of consumability for your APIs and develop your API economy.
In general, it is time to view your API's as your end user's view of the data. It is time to start designing these models as they will serve the foundation of consumability for your APIs and develop your API economy.
