See API guide
The YOUnite UI is an example of an application that consumes the YOUnite API and makes operational and Data Governance requests on behalf of the logged in user.
Five general areas of development:
- Operational - Manage zones, users, groups, roles and permissions. These requests are made using the YOUnite API.
- Data Governance - Create data domains and manage scope (ACLs). These requests are made using the YOUnite API.
- Creating and mapping source entities to YOUnite data records. This can be done with either the YOUnite API or the YOUnite message bus.
- Integrating data and keeping source entities in sync. This is managed by adaptors connected to the YOUnite message bus.
- Receiving notifications of data record changes so that applications can initiate their own work flows.
Once the operational and data governance resources are created and source records are mapped to YOUnite data records (1-3 from above), a functioning YOUnite MDM ecosystem performs three primary tasks using two separate interfaces:
Primary Task | Description | Interfaces Used |
Data Integration | Generally business logic in adaptors is kept to a minimum the sole purpose of adaptors is to both detect changes in source entities and publish them to YOUnite and to subscribe to changes published by other adaptors and process them by updating entities in the source system attached to the adaptor. | Adaptors connected to both source systems and the YOUnite message bus. |
Governance | Scopes can be managed manually by the DGS and the Zone Data Stewards (ZDSs) or they can be managed programmatically by applications when well defined events occur. For example, if a customer signs up for a new service, scope can be set so that data in a source system that already contains the customer's data is granted to a system that holds customer records for the new service. | YOUnite API |
Notifications | Changes in data can trigger events in applications and services. YOUnite allows applications and services to register for events so that they can be notified when changes occur allowing the services and applications to start their own workflows. | YOUnite API |
The YOUnite API can also act as an operational data store for retrieving records. This is generally used for systems that are not connected to YOUnite through an adaptor or when the adaptor doesn't support a data domain required by the service.
1. Zones & Permissions
zones
permissions
access tokens
UI and seeing effective permissions
Scopes
See XYZ for overview of scopes.
Inbound
Setting
Outbound
Setting
Getting Data Records
Making Data Record Changes
PUT, PATCH and Change Versions
All mutable resources contain a changeVersion
that is used as a semaphore to control concurrent access. For example, if an API consumer wants to PUT or PATCH a resource they must use the following sequence:
- GET the resource to be PUT or PATCHed
- Assemble the request body for the PUT or PATCH including the
changeVersion
returned in the GET response body above - Make the PUT or PATCH request
If the changeVersion
has been changed by another consumer since the GET request (#1 above), a 409 will be returned and the consumer will need to repeat the sequence again.
Receiving Data Record Changes
Event Notifications & Webooks
Webhooks allow applications to setup integrations which subscribe to certain YOUnite events. An API consumer integrates a webhook by following these steps:
- Create an URL endpoint where YOUnite notifications can be delivered.
- when an event occurs, a notification is triggered and an HTTP POST payload is sent to this URL endpoint.
- Register the URL endpoint with YOUnite and configure which events the consumer wants to subscribe to.
When a YOUnite subscribed event occurs, the consumer will receive an HTTP POST request and payload to the registered URL endpoint.
YOUnite Events
When registering a webhook, the consumer chooses which events they want to subscribe to. The list of subscribed events can be changed at anytime. The following is list of event types that a subscriber can be notified of on a per zone basis:
Event | Event Type |
---|---|
A zone is created | zone_post |
A zone is updated (including moved) | zone_update |
A zone is deleted | zone_delete |
A data domain is created or a new version of of the data domain has been created | domain_post |
A data domain has been updated | domain_update |
A data domain has been deleted | domain_delete |
A data record has been created for a given data domain (TBD) | dr_post |
A data record has been updated in a given data domain (TBD) | dr_put |
A data record has been deleted in a give data domain (TBD) | dr_delete |
Notification Event Response Body
The notification's response body includes the following:
key | value |
---|---|
description | A full description of the event - i.e. a full concatenation of the information described below for easy displaying. |
changeVersion | The resources change version. |
createdDate | The date the resource was created. |
Name | The resource name |
message-id | The JMS message ID. |
dateCreated | Unix timestamp of when the event notification was sent |
uuid | Zone uuid of target resource |
eventType | One of the above described "Notification Event Types" |
originatorName | The name of the zone that generated the event. |
originatorUuid | The UUID of the zone that generated the event. |
timestamp | The time the notification was created. |
actions | Some PUT & PATCH commands provide multiple actions and this list contains a description of what actions were performed. |
optional | Other key/values that are appropriate for the notification type |
Requesting Notification Log
A client can make a request to get the log history for all notifications sent to their zone. The user provides their zone and a from and to date.
Message Broker (Remove this and replace with something that doesn't cover the MB)
Response Codes
Internal Errors
It is always recommended that YOUnite is deployed in a highly-available configuration. Not only should YOUnite be highly-available but so should the underlying services that it depends upon e.g. database and message broker. If an API request is made to the YOUnite API service and one of the underlying services is experiencing a catastrophic failure, the YOUnite API service will return a 500 to the API consumer and the API consumer will have to retry their request.