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"
}
}
}
If a domain version specified a drLabel then a request for a single master data record for a domain version can be made:
GET /drs?filters=country,version:4?filters=countrycode:ALB
{
"drs": [
{
"uuid": "7c1c8a82-2de0-4719-b371-316536a9bf03",
"created_by_uuid": "da823503-20e3-4505-922a-ae2ca319ef82",
"json": "{\"capital\":{\"city\":\"Tirana\"},\"name\":\"Albania\",\"countrycode\":\"ALB\"}"
}
],
"_links": {
"_self": {
"href": "https://younite.ccc-tc.org/api/drs?filters=name%3Acountry%2Cversion%3A4%2CdrLabel%3AALB"
}
}
}
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).