Developers can retrieve master data through the YOUnite API. The differences between YOUnite Data Store and federated require different access patterns are covered here. The master data access patterns for both of these methods are covered below.
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 all master data records for a given data domain version or a single master data record.
- 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
...
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
Code Block | ||||
---|---|---|---|---|
| ||||
{
"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 specifies a drLabel
then a request for a single master data record for a domain version can be made. For example:
GET /drs?filters=country,version:4?filters=countrycode:ALB
Code Block | ||
---|---|---|
| ||
{
"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
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 http://openmdm.dev.ccctechcenter.org/apiSpecific properties for a federated data domain are designated as the fast duplicate detection properties (FDDPs or fid-dips). They are used to for:
- Ensuring duplicate data records are not created in the master data management system for a given domain version
- Fast lookup of federated master data
More on federated data domains and FDDPs can be found in the Data Domains page.
Make the Request
POST /drs/da53c1c5-945c-42fb-821f-77ea6e20302c/assembler
Code Block | ||||
---|---|---|---|---|
| ||||
{ "callbackUrl": "https://openmdm.dev.ccctechcenterproduction.ccc-co.org/openmdm-metadatadata/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
:
Code Block | ||||
---|---|---|---|---|
| ||||
{
"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 (see below).
More options such as a request timeout
, silverAdaptors
and goldAdaptors
and more can be specified in the request body. See POST /drs in the YOUnite API for more.
Callback Payload
The data is delivered in the request method body specified by notificationRegistrationType
and the callbackUrl
specified:TODO fix callback URL
Code Block | ||||
---|---|---|---|---|
| ||||
{ "callbackUrl": "https://openmdm.dev.ccctechcenterproduction.ccc-co.org/openmdm-metadatadata/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" } |
...
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?as shown in the following example:
Code Block | ||||
---|---|---|---|---|
| ||||
{ "callbackUrl": "https://openmdm.dev.ccctechcenterproduction.ccc-ct.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...
TODO add example contentThe response from the POST /drs
request includes 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
Code Block | ||||
---|---|---|---|---|
| ||||
{
"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://staff-changes.ccc-co.org/mdm-notify",
"notificationRegistrationType": "WEB_HOOK"
} |
Limit Access to a Set or a Single Adaptor
TODO explain the need. Example of what some call the Coexistence model. Add example .. no need for response content.
Other Related Endpoints
TODO: Are there any??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:
Code Block | ||||
---|---|---|---|---|
| ||||
{
"callbackUrl": "https://production.ccc-ct.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"
} |
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 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, will create an adaptor-to-domain-entry
link in the YOUnite server:
- Adaptor responding to a
GET
request for a data record at the adaptor PUT
orPOST
data event request for a given data record sent from the adaptor to the YOUnite server.