Push Notifications reference: Client API

Our Push Notifications system is currently in beta. This means you may experience errors, and the APIs may change. We would love to hear your feedback, so please get in touch!

As a pub-sub system, our Push Notifications system has two APIs: one for publishing and another for subscribing. Subscribing is done via the Client API. (Note, however, that notifications are not delivered via this API; they are delivered out-of-band via APNs and FCM/GCM.) The Client API is a RESTful HTTP API. This page describes that API and how clients can interact with it to register and subscribe to interests.

Note: This page is primarily aimed at developers writing new client libraries. If you are developing an iOS or Android app, you should use our client libraries: see our iOS client guide or our Android client guide.

The client API is intended to be used by your end users’ native app instances (almost always via Pusher client libraries such as pusher-websocket-swift and pusher-websocket-java).

The client API is principally used for registering client devices and for subscribing them to specific interests. Notifications are not delivered via this API: delivery is out-of-band via APNs and FCM/GCM.

Endpoint

This document describes the Client API with reference to an HTTP endpoint. The hosted version of our Client API is at the following endpoint:

https://nativepushclient-cluster1.pusher.com/client_api

Resource: /v1/clients

Represents the set of registered clients. Each client has the following JSON representation:

{
  "id": string,
  "platform_type": either "apns", "fcm", or "gcm"
  "token": string
}

The "token" value is an id for the client. This id was issued by the said platform. Two examples:

{
  "id": "654234",
  "platform_type": "apns",
  "token": "00fc13ad...1de8f0"  // APNs device token
}
{
  "id": "8353",
  "platform_type": "gcm",
  "token": "APAbHB3...IcZbIcg"  // GCM registration id
}

This resource accepts the following methods:

  • POST /v1/clients. The request body is a client in the above representation, without the id key (which is issued by us), and including a app_key key. The schema is then:

    {
      "app_key": string,
      "platform_type": either "apns", "fcm", or "gcm"
      "token": string
    }
    

    A successful response has status 201 Created, and the body is the new client, including the generated id key issued by us.

Resource: /v1/clients/:client_id/token

Represents a client with the id :client_id. Each client has the JSON representation above.

This resource accepts the following methods:

  • PUT /v1/clients/:client_id/token. A valid request has a client in the JSON format above, including both the "platform_type" and "token" keys. If and when clients get an updated token from their platform, they are expected to call this to update us.

    This is principally required for FCM/GCM. If we have an expired token in the database and push, it will go through, and also give us the new refreshed token. While it’s expired, if the app re-registers to the above route with the new token, we will get the new token too. Therefore we may have two clients in the database to which we can push, and might send the same user a duplicate push. The Android library should save its client_id in SharedPreferences. When it gets a FCM/GCM-initiated refresh request, it will use its client ID and make this PUT request to us. That way we can keep track of the newest token for that device.

Resource: /v1/clients/:client_id/interests

Each interest name can be up to 164 characters. Each character in the name must be an ASCII upper- or lower-case letter, a number, or one of _=@,.;. Note that the hyphen (-) is not a valid character in interest names. This character is reserved for the possibility in future of marking interest names with prefixes (such as private- or presence-).

Represents the set of all interests which the client with id :client_id is subscribed to.

GET /v1/clients/:client_id/interests?cursor=${cursor}&limit=${limit}

This returns the client’s interest set. This resource is paginated; each response can return up to 1000 interests. The page is controlled with two optional query parameters:

  • cursor: determines the start point. If cursor is omitted or empty, the first page of interests will be returned. If cursor is supplied, it must be a string gained from a response to a previous page request.
  • limit: the maximum number of interests returned in the response. This can be up to 1000.

The response format is as follows. If next_cursor is null, this is the final page of interests. Otherwise, there may be more interests, which can be found by using the next_cursor value as the cursor query parameter in a future request.

{
  "interests": [string],
  "response_metadata": {
      "next_cursor": null | string
  }
}

PUT /v1/clients/:client_id/interests

This updates the the client’s interest set to that given in the interests key of the body. Equivalently, it subscribes the client to all interests in that set, and unsubscribes the client from all interests not in that set. Requests to this resource must provide a valid AppKey in the body.

{
  "app_key": string,
  "interests": [string]
}

Resource: /v1/clients/:client_id/interests/:interest_name

Each interest name can be up to 164 characters. Each character in the name must be an ASCII upper- or lower-case letter, a number, or one of _=@,.;. Note that the hyphen (-) is not a valid character in interest names. This character is reserved for the possibility in future of marking interest names with prefixes (such as private- or presence-).

Represents the subscription of the client with id :client_id to the interest with name :interest_name.

Requests to this resource must provide a valid AppKey in the body like so

{
  "app_key": string,
}

This resource accepts the following methods:

  • POST /v1/clients/:client_id/interests/:interest_name. This subscribes the client to the interest with the given name.

  • DELETE /v1/clients/:client_id/interests/:interest_name. This unsubscribes the client from the interest with the given name.

Have you tried using the search to find what you’re after? If you still have a question then get in touch with us and let us help you out.