Developers can retrieve master data through the YOUnite API. The differences between YOUnite Data Store and federated require different access patterns.
Federated vs YOUnite Data Store Access Patterns
- YOUnite Data Store - Master data records requests are synchronous and can be made for a single master data record or a page of master data records.
- federated - A request for a single master data record is made asynchronously. The consumer needs to provide a callback URL to YOUnite where the assembled master data record can be delivered. When YOUnite receives the request for the federated data record, it:
- Looks up what systems/adaptors contain the data record
- Consults the appropriate inbound/outbound ACLs (Governance), requests
- Makes a request for the data at the appropriate systems
- Assembles the data based on Gold/Silver adaptor status (if any have been configured or added to the request)
- Delivers the assembled record to the consumer's callback URL.
YOUnite Data Store Access Pattern
Make the Request
Payload
Federated Access Patterns
blah blah about federated access... more can be found in the https://younite.us/api
TODO - Do we want to make a deal of the coexistence model??
Search a Domain Version's FDDPs
what is a FDDP (pointer to more). TODO - add request a response payload example
Make the Request
TODO... Default timeout is, it can be overriden using
TODO fix callbackURL
POST /drs/da53c1c5-945c-42fb-821f-77ea6e20302c/assembler
{ "callbackUrl": "https://openmdm.dev.ccctechcenter.org/openmdm-metadata/6c5a754b-6ce0-4871-8dec-d39e255eccc3/drs/da53c1c5-945c-42fb-821f-77ea6e20302c/assembler", "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3", "timeout": 10, "notificationRegistrationType": "WEB_SOCKET" }
TODO response
Callback Payload
The data is delivered in the request method body specified by notificationRegistrationType and the callbackUrl specified:
TODO fix callback URL
{ "callbackUrl": "https://openmdm.dev.ccctechcenter.org/openmdm-metadata/6c5a754b-6ce0-4871-8dec-d39e255eccc3/drs/da53c1c5-945c-42fb-821f-77ea6e20302c/assembler", "oneTimePad": null, "data": { "zip": "46406", "lastName": "Jadczak", "address": "959 Barby Place", "gender": "F", "city": "Gary", "lastVisit": "2013-01-12", "birthDate": "1978-03-25", "firstName": "Viki", "phone": "219-375-6563", "customerId": "0A0V6HWEIL", "serviceRep": "Eileen", "state": "IN", "accountBalance": 1666.78, "email": "ejadczak5@cbslocal.com" }, "assemblerUuid": "25e1b386-48db-45b9-a8e9-dc1499c56e23", "notificationRegistrationType": "WEB_SOCKET" }
Gold/Silver Adaptors
The zone data steward or the API consumer can specify gold and silver adaptors (TODO: New page or gold/silver and put a link to it here). To override the zone's default gold and silver adaptor specify the UUIDs of the goldAdaptors or silverAdaptors in the assembler request payload. TODO - add UUIDs and are they quoted or not?
{ "callbackUrl": "https://openmdm.dev.ccctechcenter.org/openmdm-metadata/6c5a754b-6ce0-4871-8dec-d39e255eccc3/drs/da53c1c5-945c-42fb-821f-77ea6e20302c/assembler", "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3", "goldAdaptors": { "uuids": [] }, "silverAdaptors": { "uuids": [] }, "timeout": 10, "notificationRegistrationType": "WEB_SOCKET" }
Metadata payload
TODO the metadata for the request can be retrieved...
{ "uuid": "a9e49f65-97ad-45e3-94ac-9bc771b7fcec", "drUuid": "da53c1c5-945c-42fb-821f-77ea6e20302c", "status": "RESPONSE_SENT", "requestedProperties": [ "zip", "lastName", "address", "gender", "city", "lastVisit", "birthDate", "firstName", "phone", "customerId", "serviceRep", "state", "accountBalance", "email" ], "goldAdaptors": { "uuids": [ "80121e99-516d-445a-9cbe-7915280c4d42", "f96f8385-5a6d-47f4-a784-5bfca05af35d" ] }, "silverAdaptors": { "uuids": [ "d798d987-afd0-4cd1-8830-5e7627a69f2e", "f8264016-f8bf-4bab-8b2e-fb5a845d2d50" ] }, "capableAdaptors": { "uuids": [] }, "invokeCallbackOn": "GOLD_SILVER", "timeout": 7, "zoneUserUuid": "9ef2f7e2-ceca-499d-9664-7c8f8c2ea9a0", "zoneUuid": "d3b70b3a-9c5f-4ef4-bc70-54b713e46854", "callbackUrl": "http://{{callback_ip}}:8082/notify", "notificationRegistrationType": "WEB_HOOK" }
Limit Access to a Set or a Single Adaptor
A request for a federated data record can be limited to one or more adaptors by specifying the adaptor(s) UUID in the capableAdaptors property in the request payload:
{ "callbackUrl": "https://openmdm.dev.ccctechcenter.org/openmdm-metadata/6c5a754b-6ce0-4871-8dec-d39e255eccc3/drs/da53c1c5-945c-42fb-821f-77ea6e20302c/assembler", "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3", "capableAdaptors": { "uuids": ["2946c735-6bcb-4383-9753-cf09e41d8360"] }, "timeout": 10, "notificationRegistrationType": "WEB_SOCKET" }
Limiting a request to a known system is referred to a Coexistence model where master data is distributed but generally held on a single system holding a golden copy.
Check if Data Record is Mapped at a Specific Adaptor
To check if YOUnite server has an adaptor-to-domain-entry link for a given master data record at an adaptor.
GET /drs/{uuid}/adaptor/{adaptorUuid}/check
If the link exists a 200 OK is returned and a 404 NOT FOUND if not.
NOTE: A NOT FOUND is not a definitive result since the YOUnite server makes no assumptions if a POST DR (data record )request sent to an adaptor was honored by the adaptor and does not create the server does not create the adaptor-to-domain-entry link until the adaptor sends a data event back to the YOUnite server for a given DR. The following two events, are examples of events that will create an adaptor-to-domain-entry link in the YOUnite server:
- Adaptor responding to a GET request.
- PUT or POST data event request (sent from the adaptor to the YOUnite server).