Viewing the Activity Log

In globaliD, an activity is something that happens to an identity that is relevant to that identity. The identity will typically be notified about any new activities using push notification, and there is also an activity log which can be viewed to see the list of activities and the details of each individual activity.

Activities are generated internally; you cannot create new activities via the API. However, you can view the contents of the activity log using the various /v1/activities API endpoints. Activities can also be marked as read; new activities are automatically marked as unread, and you can change this status using the API.

Activity Types and Subtypes

Each activity has a type which broadly identifies the nature of the actity. Some activity types also have multiple subtypes identifying in more detail what that activity entailed. To see what activity types (and subtypes) are available, use the GET /v1/activities/types endpoint, like this:

Request:

   GET /v1/acticities/types
   BEARER <access_token>

Response:

   HTTP/1.1 200 OK

   {
     "data": [
       {
         "name": "...",
         "description": "...",
         "subtypes": [
           {
             "id": "...",
             "name": "...",
             "description": "..."
           },
           ...
         ]
       },
       ...
     ]
   }

This can be used to initialise your app's UI if you are implementing an activity log viewer, for example by populating the various filter pop-up menus.

Downloading the Activity Log

To download the activities in the log, you can use the GET /v1/activities API endpoint. For example:

Request:

   GET /v1/activities
   BEARER <access_token>

Response:

    HTTP/1.1 200 OK

    {
      "data": [
        {
          "uuid": "...",
          "title": "...",
          "description": "...",
          "type": "...",
          "subtype": "...",
          "is_push_sent": true,
          "is_read": false,
          "reference_uuid": "...",
          "gid_uuid": "...",
          "meta_data": "...",
          "created_at": "...",
          "updated_at": "..."
        },
        ...
      ],
      "meta": {
        "page": 1,
        "per_page": 50,
        "total": 107
      }
    }

For each activity, the following information is returned:

  • uuid: a unique UUID identifying this activity.
  • title: a title summarising the activity.
  • description: a more detailed description of the activity.
  • type: the name of the activity's type.
  • subtype: if this activity has a subtype, this will be the ID of the subtype.
  • is_push_sent: has a push notification been sent for this activity?
  • is_read: has this activity been read by the user?
  • reference_uuid: an optional UUID used to identify this activity within the service that created it.
  • gid_uuid: the UUID of the identity this activity relates to.
  • meta_data: optional metadata associated with this activity, in the form of a stringified JSON object.
  • created_at: the date and time at which this activity was created, in ISO-8601 format.
  • updated_at: the date and time at which this activity was last updated, in ISO-8601 format.

The meta object returns information allowing you to paginate the results; to change the number of activities returned per page, use the per_page parameter, like this:

`GET /v1/activities?per_page=100`

To retrieve multiple pages of results, you use the page parameter, like this:

`GET /v1/activities?page=1`
`GET /v1/activities?page=2`
`GET /v1/activities?page=3`
...etc

Note that page one holds the most recent activities, and subsequent pages go further back in time.

You can also filter the list of returned activities in various ways, using the following query-string parameters:

  • type: an array of activity types. Only those activities with the specified type(s) will be returned.
  • subtype: a subtype. Only those activities with the given subtype will be returned.
  • reference_uuid: a reference UUID. Only those activities with the given reference UUID value will be returned.

Marking Activities as Read

Since the purpose of the GET v1/activities endpoint is to show the activity log to the user, it is helpful to be able to mark the various activities as having been read by the user. When downloading the activities, each activity has an is_read field that can be used to visually highlight the unread activities. If the user then reads the details of that activity (for example, by tapping on the activity to drill down and view the activity's details), you can mark the activity as read.

There are two ways in which you can mark activities as read. The simplest approach is to mark an individual activity by UUID value, like this:

Request:

   POST /v1/activities/<uuid>/read
   BEARER <access_token>

   {
     "read": true
   }

Response:

   HTTP/1.1 204 No Content

You can also call this endpoint with read set to false to mark an activity as unread if you wish.

As well as marking individual activities as read or unread, you can also use the POST /v1/activities/read endpoint to mark all activities matching a given type or subtype as being read or unread. For example:

Request:

   POST /v1/activities/read
   BEARER <access_token>

   {
     "isRead": true,
     "type": "...",
     "subtype": "..."
   }

Response:

   HTTP/1.1 204 No Content

type is the name of the desired type, and subtype is the name of the desired subtype, if any. Note that the subtype is optional.

Finally, you can obtain a count of the number of unread activities, grouped by type and subtype, by calling the GET /v1/activities/unread-count endpoint:

Request:

   GET /v1/activities/unread-count
   BEARER <access_token>

Response:

   HTTP/1.1 200 OK

   {
     "unread": 20,
     "types" {
       "...": {
         "total": 20,
         "subtypes": {
           "...": 15,
           "...": 5
         }
       }
     }
   }

::TODO: Check that this structure is correct. The Swagger file is a bit confusing::

The various fields in the types object are type names, mapping to the total number of unread activities of that type, along with a breakdown by subtype if appropriate. The fields in the subtypes object map the subtype name to the number of unread activities for that subtype.