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
To retrieve a list of master data records for a given domain version:
GET /drs?filters=domain-name,version:version-number
For example:
GET /drs?filters=country,version:4
{ "drs": [ { "uuid": "fbf6cfdf-d240-4843-9bd7-8e99ad7480c6", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"Kabul\"},\"name\":\"Afghanistan\",\"countrycode\":\"AFG\"}" }, { "uuid": "a9b1e4e1-fdf0-43e1-91f5-384c728cecee", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"Luanda\"},\"name\":\"Angola\",\"countrycode\":\"AGO\"}" }, { "uuid": "88c66722-8078-4e81-932f-d09f134d4130", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"The Valley\"},\"name\":\"Anguilla\",\"countrycode\":\"AIA\"}" }, { "uuid": "c35c753a-a246-4959-97ca-bd108a9833c1", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"Mariehamn\"},\"name\":\"Åland Islands\",\"countrycode\":\"ALA\"}" }, { "uuid": "7c1c8a82-2de0-4719-b371-316536a9bf03", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"Tirana\"},\"name\":\"Albania\",\"countrycode\":\"ALB\"}" }, { "uuid": "124d861b-c5a9-4198-8724-760f1d7bcefb", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"Abu Dhabi\"},\"name\":\"United Arab Emirates\",\"countrycode\":\"ARE\"}" }, { "uuid": "87da0d10-d96f-4e7b-ade5-b3b7aa290ab2", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"Yerevan\"},\"name\":\"Armenia\",\"countrycode\":\"ARM\"}" }, { "uuid": "a5a5befa-89d9-4412-98e1-6278616ec3df", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"Pago Pago\"},\"name\":\"American Samoa\",\"countrycode\":\"ASM\"}" }, { "uuid": "aced6d65-de04-43e8-8993-8e5d0e7bc8aa", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"Saint-Pierre, Réunion\"},\"name\":\"French Southern Territories\",\"countrycode\":\"ATF\"}" }, { "uuid": "49025a51-9530-4cef-afc8-696ff97d1e1e", "created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82", "json": "{\"capital\":{\"city\":\"St Johns\"},\"name\":\"Antigua and Barbuda\",\"countrycode\":\"ATG\"}" } ], "_links": { "_self": { "href": "https://younite.ccc-tc.org/api/drs?filters=name%3Acountry%2Cversion%3A4&page=0&size=10" }, "_next": { "href": "https://younite.ccc-tc.org/api/drs?filters=name%3Acountry%2Cversion%3A4&page=1&size=10" } } }
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://production.ccc-co.org/data/6c5a754b-6ce0-4871-8dec-d39e255eccc3/drs/da53c1c5-945c-42fb-821f-77ea6e20302c/assembler", "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3", "timeout": 10, "notificationRegistrationType": "WEB_SOCKET" }
POST response. Note there is no data delivered since it will be delivered to the location specified in the request body's callbackUrl:
{ "assemblerUuid": "a9e49f65-97ad-45e3-94ac-9bc771b7fcec", "drUuid": "da53c1c5-945c-42fb-821f-77ea6e20302c", "location": "https://younite.ccc-co.org/api/drs/da53c1c5-945c-42fb-821f-77ea6e20302c/assembler/a9e49f65-97ad-45e3-94ac-9bc771b7fcec" }
The response includes a location the consumer can use to retrieve metadata about the request:
Callback Payload
The data is delivered in the request method body specified by notificationRegistrationType and the callbackUrl specified:
{ "callbackUrl": "https://production.ccc-co.org/data/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
The POST /drs/<dr-uuid>/assembler response included a location the consumer can use to retrieve metadata about the request. For example:
GET https://younite.ccc-co.org/api/drs/da53c1c5-945c-42fb-821f-77ea6e20302c/assembler/a9e49f65-97ad-45e3-94ac-9bc771b7fcec
{ "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).