Skip to content

Architecture

architecture-overview.png

The picture above illustrates the main workflows that will be part of the life of any integration made with the Data API. In practical terms:

  1. Registering a Webhook Subscription - the first thing that needs to be done is to register a Webhook Subscription. It will allow one to receive HTTP requests with the modifications that happens in the NurtureCloud system.
  2. Receive Realtime Notifications - Once a Webhook Subscription is registered, Data API will automatically relay realtime notifications to the desired web endpoint.
  3. Synchronising Previously Created Data - Data API stores a copy of every piece of information available in the NurtureCloud system. By using the Sync All endpoint of a given business component, you will be able to synchronise everything created before you have registered your subscriptions.

Authentication

All Data API endpoints are protected. One must provide sufficient credentials or no access will be granted.

Main concepts

Our web api will be designed to act as an RPC layer over HTTP - instead of following REST semantics - and it will be consistently enforced across all of our endpoints. We will also ensure that all operations will be executed asynchronously, notifying the client which the result once the operation is finished.

In practice:

  • There will be only three types of operations exposed on our API:
    1. sync operations
    2. modifying operations
  • By design, there will be no way for 3rd-party services to use our API to search for any specif data.
  • All endpoints will return 202 - Accepted - being it a sync or a modifying operation.
  • All endpoints will be exposed using the HTTP verb POST.
  • All endpoints are Business Aware - meaning that the BusinessId will be enforced in the URL
  • The common baseURL prefix for all endpoints will be: /v1/business/:businessId/
  • All results will be sent through webhook notifications.

With regard to Webhook Notifications, there's a dedicated page with more details about it at Webhook. For the sake of the architecture overview of it:

  • A Notification Subscription is a way to register HTTP endpoints to receive information.
  • It allows one to define whether subscriptions to define the scope of information it will be receiving (Agents, Business, etc).
  • Clients can register as much webhook subscriptions as they need.
  • There are two types of sources of information that will trigger notifications:
    1. Realtime notifications triggered as users modify data
    2. The results of sync operations

With regard to sync operations:

  • they will be limited to two types of operations: Sync By ID (SBI) and Sync All Data (SAD)
  • SBI endpoints will have the URL suffix: /sync-by-id?id=:id
  • SAD endpoints will have the URL suffix: /sync-all
  • All operation results will be notified through Webhooks in which the payload will have the found content. We won’t be notifying the client in case we could not find any data.

With regard to Modifications:

  • Creations will have the URL suffix: /create
  • Updates will have the URL suffix: /update/:id
  • Delete operations will have the URL suffix: /delete/:id
  • Correlation operations will have the URL suffix: /correlate/:id
  • All modifications will be propagated into our infrastructure. Once finished, you will receive Realtime notifications into your subscriptions.