Canonical Modeling For API Interoperability

1y ago

20 Views

1 Downloads

2.08 MB

35 Pages

Report/dmca

Download PDF

Transcription

Overview How APIs help developers, how they don’t Canonical models: promises and challenges Tackling variability in message representations A Better Client Library Demo and walkthroughCOPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.2

Services Built in isolation Many services built toservice a singleapplication or org unit. No data or APIgovernance, no shareddata models. No meaningfulguidelines. “Just useschema.” No easy path to eventualintegration or promotionto shared services.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.4

A Modest Proposal Define a common model forall data communicatedbetween systems. Common recommendationin one form or another Patterns of Enterprise Integration(Fowler) SOA Design Patterns (Erl)COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.14

Different Uses for Canonical DataModels:API DesignIntegration SOA Governance: Enforceconsistency with the canonicalmodel (“canonical schema”) Tools: Compose message formatsfrom canonical data modelsSDK Development Abstract physical format Optimize for performance and/ordeveloper productivity Transform messages to/fromcanonical format. Boundary translation to/fromindustry standardsAnalysis Analyzing data landscape, servicelandscape Compliance, internal audit, MDM,large-scale integration efforts.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.15

Why is this so hard?Intrinsic ChallengesModeling Mismatch: Viewpoint Getting everyone to the table, getting toagreement Versioning, Change impact analysis, andlifecycle managementEconomic Alignment Challenges Service developers need to get it done Code-first frameworks promise low-costto service developers What's the purpose of the model? What level of abstraction? What level ofdetail? How does it related to concreterepresentations?Modeling Mismatch: Languageand Method ER, UML, OWL, etc. The attractive nuisance of XML SchemaResult: confusion about what thecanonical model is supposed tobe.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.16

The Pervasive Problem: Variability One size fits none Message representations vary by Level of detail Perspective Topology, Granularity Contextual constraints MetadataCOPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.17

Another Look at the Variability Problem There’s a common theme(canon) underneath thesevariations. Can we describe the themeand variations separately? Can we model the variationsas adaptations,augmentations of the theme? There’s a name for that:Realization.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.19

Realization: Property SubsetAPI requests orresponses mayonly need a subsetof propertiesdefined in thecanonical model.Realization modelmay specify a listof includedproperties.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.20

Realization:PerspectiveMessage and resourcestructures projectdifferent views from thesame logical data modelCanonical model shouldsupport bi-directionalreferences.Realization model shouldallow embedded or linkedrepresentations.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.21

Realization:MetadataBusiness Information ModelPartyParty IDName1Account0.n Account IDBalanceMarginStatusData Aspects····DeltasData SourceData SecurityExplicit Null Values.APIs may need to augmentessential data with descriptivemetadata.Message StructureData aspects are cross-cuttingconcerns that may be woventogether with canonical dataas part of the interfacerealization. party dataSource “MSDB” partyId 123 /partyId partyName xsi:nil “true” nullValue “Not Available” / accounts account dataSource “A2” transType “insert” accountId XYZ /accountId balance xsi:nil “true” isRestricted “true” / /account /accounts /party COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.22

Realization: Contextual ConstraintsServices may have specificconstraints that are notintrinsic to the datadefinitions.Realization model mayspecify constraints onrequests or responses.Constraints may takedifferent forms: range,subtype, logicalexpression, etc.TradeAssetClass BondCOPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED. 10MM23

Canonical Modeling Reloaded New understanding of the model vs. message: Canonical data models describe business information at the conceptual level Semantically rich Technology independent Realization models afford variability, with clear limits Bend the canonical model, don’t break it Realized representations must be recognizable as instances of the canonical model. Some new terms: Interface Data Model: A realization model used to define data exchanged through an API. Resource Data Model: An interface data model for a RESTful (resource-oriented) API.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.24

How many ways from Sunday does thissuck?1.2.3.4.5.Canonical data model gets lost in the translation.Awkward structures introduced by message format.Annotations are specific to a single API, message format.Not usable as business objectsExtra code to populate these DTOs, move data between them andinternal representations.6. High memory footprintJust say noto DTO.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.27

CanonicalSerializerNo DTOs, no need tocode transformationsSingle object graphserialized to multipleRDMs, messageformats.Canonicalclasses/interfaces canbe used as businessobjects.Flexibility: pluggableformats for canonicalmodel, RDM, objectgraph and media type.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.28

Canonical Serializer: ImplementationWhat do we call a serializer thatshoots representations out of a canon?Kaboom t a demo now, but feedback & contributions welcome.)COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.29

Scenario TaxBlaster: new tax preparation app. Integrates with e-filing service Integrates with client billing service Common data model, different viewsCOPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.30

TaxBlaster: Canonical Data ModelTaxFilingfilingID : stringjurisdiction : stringcurrency : stringyear : dateperiod : intgrossIncome : decimaltaxLiability : decimalAddressPersontaxpayer1.1taxpayerID : stringlastName : stringfirstName : stringotherNames : string*employees0.*employer0.10.*addressesstreet 1 : stringstreet2: stringcity : stringstateOrProvince : stringpostalCode : stringCompanycompanyID : stringcompanyName : stringEIN : stringform : stringactive : booleanCOPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.31

Internal alDataTypename : stringPluggableimplementations: CDM RDM Canonical ObjectReader/Writer Serializer0.*name : typropertiesCDMPropertyname : stringcardinality : Cardinalityname : stringcardinality : yRDMReferencePropertytype : primitiveDataTypeCDMReferencePropertytype : enceEmbedlinkRelation : stringCOPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.32

Recipe for a model-oriented API client A canonical modeling language Data available at runtime that conforms to the canonical model An API description facility that Realizes the canonical model as an Interface Data Model Described as formalized variations A runtime serializer/deserializer that Interprets the API model Serializes and deserializes between the the canonical object graph and thethe realized message format.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.33

ConclusionCanonical models are a way to capture organizational agreement ondata definitionsWe need the right degree of coupling between the canonical modeland API representations.We do this by identifying the kinds of variations that we need tosupport, and formalizing these in a realization mapping.Tooling can support realization modeling and apply it in client libraries,SDKs, middleware, etc.Potential benefits: better interoperability, lower integration cost,higher developer productivity.COPYRIGHT 2014, MODELSOLV, INC. ALL RIGHTS RESERVED.34

Different Uses for Canonical Data Models: API Design SOA Governance: Enforce consistency with the canonical model ("canonical schema") Tools: Compose message formats from canonical data models SDK Development Abstract physical format Optimize for performance and/or developer productivity Integration Transform messages to/from