Push Notifications reference: Client API

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. If there is a mismatch between the interests the client registered for and the interests added, the client library should handle this.

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/: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.