API Documentation

Registering for Notifications ¶

Notifications allow applications to instantly know when certain data has changed, or certain user actions has been performed. Correct implementation of notifications allows user to use multiple devices, with the data always being up-to-date.

To receive notifications, the Grid app needs to be registered as a client application.

The notifications sent to clients follow the notifications schema. For how to deal with particular notifications, see the recommendations found below.

When reacting to an action the client needs to make the request using the regular Bearer token.

Content-Type: application/json

[
{
"client": "cnhq98f3h92cg0c",
"type": "gcm"
}
{
"client": "jipcen3i2h3f0823h0f",
"type": "apn_production"
}
]

Content-Type: application/json

{
  "client": "cnhq98f3h92cg0c",
  "type": "gcm"
}

{
  "id": "client.json",
  "$schema": "http://json-schema.org/draft-04/schema",
  "title": "Client App",
  "description": "",
  "type": [
    "object"
  ],
  "properties": {
    "client": {
      "type": "string",
      "description": "Client identifier for the messaging protocol"
    },
    "type": {
      "type": "string",
      "description": "Type of the client",
      "enum": [
        "gcm",
        "apn_production",
        "apn_development"
      ]
    }
  },
  "required": [
    "client",
    "type"
  ]
}

Location: /client/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

Content-Type: application/json

{
  "id": "notification.json",
  "$schema": "http://json-schema.org/draft-04/schema",
  "title": "Client Notification",
  "description": "",
  "type": [
    "object"
  ],
  "properties": {
    "type": {
      "type": "string",
      "description": "Message type",
      "example": "sync"
    },
    "text": {
      "type": "string",
      "description": "Message to show"
    },
    "title": {
      "type": "string",
      "description": "Title of the notificatio"
    },
    "url": {
      "type": "string",
      "example": "https://thegrid.io",
      "description": "The site or page which the notification refers to. Opening this URL should be the default action for the notification if it is provided"
    },
    "icon": {
      "type": "string",
      "description": "URL for icon to show in the notificatio"
    },
    "preview": {
      "type": "string",
      "description": "URL to a large icon, used for rich notifications on Android Wear and Chrome extension"
    },
    "actions": {
      "type": "array",
      "description": "List of possible Actions to take from the notification",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Text label for the action"
          },
          "icon": {
            "type": "string",
            "description": "URL to an icon for the action"
          },
          "path": {
            "type": "string",
            "description": "HTTP REST path that client should use when activating the action"
          },
          "method": {
            "type": "string",
            "description": "HTTP method to use for the call",
            "enum": [
              "POST",
              "GET"
            ]
          },
          "payload": {
            "type": "object",
            "description": "Object to pass as payload to when activating action"
          }
        },
        "required": [
          "label",
          "icon",
          "path",
          "method"
        ]
      }
    }
  },
  "required": [
    "title",
    "text"
  ]
}

Available Notifications ¶

Synchronization ¶

These notification payloads are intended for API clients to refresh changed data from the server. They are not indended to be visualized except for possible data changes in the UI (new items appearing, site configs changing, etc).

User events:

• user_merge: user account has been merged with another one. All data should be re-fetched

• user_removed: the user account has been disabled. Remove data and disable application usage

• user_activated: the authenticated user’s account has been activated. Re-fetch data and enable full application usage. This one may be worthy of notifying user visually

Item events:

• new_item: new item has been created, fetch with id

• updated_item: item has been updated, fetch with id

• published_item: item has been published to sites, update display accordingly. Fetch with id if needed

• unpublished_item: item has been unpublished from sites, update display accordingly. Fetch with id if needed

• removed_item: item has been deleted. Remove from app

Site events:

• new_site: new site has been created, fetch with id or use repo

• updated_site: site has been updated, fetch with id or use repo. These can be also caused by site publishing process

• removed_site: site has been deleted. Remove from app

Redesign events:

• started_redesign: new redesign is being worked on, available from listing with ?inflight=true

• new_redesign: new redesign is available for the site, fetch with id

• updated_redesign: redesign has been updated (usually with a rating), fetch with id

• removed_redesign: redesign has been removed. Remove from app

Job status ¶

The job status notifications are related to long-running operations initiated by the user or a back-end process that the user should be aware of. These should be shown with persistent progress indicators either in the system’s notifications are or in the context of the action made (for example, a “loading” item card).

Job events contain the following information:

• job_id: identifier for the long-running job, can be used for polling the job endpoint

• item: item ID associated with the job, if any

• job_type: type of the job, currently either share or publish

Job status changes cause the following events to be sent:

• started_job: job has started. Show progress notification accordingly

• updated_job: there has been progress on the job. Possibly move progress indicator one step forward

• failed_job: job has failed. Replace progress notification with a failure indicator

• completed_job: job has completed. Remove progress notification or replace with a success indicator

Actionable notifications ¶

These notifications are related to something urgent the user should be able to react to. They should be shown as OS-level notifications that may have additional information like screenshots or action buttons associated with them.

Notifications from the molly AI:

These notifications are meant to be shown visually, and contain the texts written by the AI to the user. In general, they have the molly collapse key if available on the platform.

Molly notifications contain the following keys:

• type: subtype of the notification, for example review or publish

• title: textual title for the notification

• text: full notification text

• url: URL that the user can visit to see more related to the notification, for example a newly redesigned website of theirs

• preview: Screenshot for the URL above, if any

• ipfs: IPFS hash for the URL, if any

• site: ID of the site associated with the notification

• job: ID of the job associated with the notification, if any. Can be used to morph job progress to visual notification

• actions: array of potential additional actions that user can perform, each containing label, icon, path, method, and payload

Molly notification types:

• review: The AI has multiple designs for the user to review and choose from

• publish: A new version of the site or some pages within is now live