Dartmouth API Developer Portal

Resource Changes - Public API

Description

Many applications that consume web services can benefit from resource change notifications. By creating subscriptions, consumers can find out when a resource is changed. For example, an application may need to present accurate and up-to-date information about Faculty members. It is inefficient to repeatedly query the People API to obtain the entire subset of People who are Faculty, then retrieve the public information for that entire subset. It is unlikely that every Faculty member's information has changed since the time of the initial load.

The solution, then, is to create a subscription to the People resource, where the subscriber can obtain a list of the ids for only those Faculty members whose data has changed.

With the Resource Changes API, you can:

• create and subscribe to a resource change message queue
• retrieve messages from the queue
• delete messages from the queue
• unsubscribe from the queue

How subscriptions work

After creating a resource_change subscription, messages will begin to accumulate in the subscription's queue. Messages are created when a process modifies the resource in some way and then publishes a change message to all subscribing queues for that resource. A resource is considered changed if it is added, removed or modified.

A consumer application that retrieves messages from the subscription queue is typically called a worker. The recommended process flow for a worker application using the queue is to:

• retrieve one or more messages from the queue
• perform whatever processing is desired (including local caching) for each message retrieved
• delete messages from the queue after they are successfully processed

A single consumer account can subscribe to a single resource message queue multiple times for different use cases. The subscription_name you assign to the subscription allows you to keep track and manage your subscriptions individually.

Message Retention

Subscribers are expected to delete messages from their subscription queues as they are processed.

NOTE: Messages may be automatically deleted 14 days from their creation date.

Message format

Messages are returned as a JSON array of change message objects. The format of a change message object is small and straightforward:

[
    {
        "resource": "people",
        "subscriber_netid": "f0040pp",
        "subscription_id": "5d14cdf70879076e4452742b",
        "subscription_name": "f0040pp people CSGold feed",
        "created_date": "2019-06-27T14:09:44.251833Z",
        "message": {
            "id": "f000000"
        },
        "id": "5d14ce28fffdae32cceb9543"
    },
    {
        "resource": "people",
        "subscriber_netid": "f0040pp",
        "subscription_id": "5d14cdf70879076e4452742b",
        "subscription_name": "f0040pp people CSGold feed",
        "created_date": "2019-06-27T14:09:44.254339Z",
        "message": {
            "id": "f000001"
        },
        "id": "5d14ce28fffdae32cceb9544"
    }
]

where:

Resource Changes API Requests

For all endpoints, an HTTP status code of 200 indicates success, a 404 code indicates that the resource or message was not found, and a 500 code indicates a bad request. Payload returned with a 500 response contains a descriptive message as to why the request was considered bad.

Subscribe to a Resource Change queue

POST /api/resource_change/subscriptions

Required Headers

Authorization: Bearer {jwt}

Required Scope

No scope is required for this API endpoint.

Required body

The request body must contain a valid JSON object containing the following attributes:

{
    "subscriber_netid": "f0040pp",
    "resource": "people",
    "name": "f0040pp people CSGold feed",
    "description": "used to feed people changes to CSGold"
}

Returns

{
    "subscriber_netid": "f0040pp",
    "resource": "people",
    "name": "f0040pp people CSGold feed",
    "description": "used to feed people changes to CSGold",
    "created_date": "2019-06-27T14:05:06Z",
    "created_by": "f0040pp",
    "id": "5d14cd120879076e44527428"
}

Unsubscribe to a Resource Change queue

DELETE /api/resource_change/subscriptions/{id}

Required Headers

Authorization: Bearer {jwt}

Required Scope

No scope is required for this API endpoint.

Required body

none

Returns

{}

Notes on usage

Subscriptions are managed are modeled as RESTful resources. Therefore they can be created with a POST or deleted with a DELETE request. PATCH and PUT are not supported for updates. Once a subscription is created it immediately becomes available to recieve new messages by message producers. Deleting a subscription does not delete existing messages for that subscription, but messages may expire 14 days from creation and be deleted.

Get Subscription status

GET /api/resource_change/subscriptions

Required Headers

`Authorization: Bearer {jwt}`

Required Scope

No scope is required for this API endpoint.

Returns

[
    {
        "subscriber_netid": "f0040pp",
        "resource": "people",
        "name": "f0040pp people CSGold feed",
        "description": "used to feed people changes to CSGold",
        "created_date": "2019-06-27T14:08:55Z",
        "created_by": "f0040pp",
        "id": "5d14cdf70879076e4452742b"
    }
]

A payload containing an array of all subscriptions is returned. The id of the subscription can be used to subsequently delete the subscription.

Get messages from subscription

GET /api/resource_change/messages

Returns an array of messages for the subscriber from all subscriptions. To return messages from a particular resource or subscription, standard filtering and paging as described in the Filtering and Paging section of the docs can be used. The return from the GET will return an X-Total-Count header with the total number of messages returned from the query as shown in the following screenshot:

Required Headers

`Authorization: Bearer {jwt}`

Required Scope

No scope is required for this API endpoint.

Returns

[
    {
        "resource": "people",
        "subscriber_netid": "f0040pp",
        "subscription_id": "5d14cdf70879076e4452742b",
        "subscription_name": "f0040pp people CSGold feed",
        "created_date": "2019-06-27T14:09:44.251833Z",
        "message": {
            "id": "f000000"
        },
        "id": "5d14ce28fffdae32cceb9543"
    },
    {
        "resource": "people",
        "subscriber_netid": "f0040pp",
        "subscription_id": "5d14cdf70879076e4452742b",
        "subscription_name": "f0040pp people CSGold feed",
        "created_date": "2019-06-27T14:09:44.254339Z",
        "message": {
            "id": "f000001"
        },
        "id": "5d14ce28fffdae32cceb9544"
    }
]

Delete Resource Change Message

A message is deleted from a resource changes subscription queue by using this endpoint, passing the message's id as the last segment in the URI.

Required Headers

Authorization: Bearer {jwt}

Required Scope

No scope is required for this API endpoint.