Skip to content

Home

Jump to bottom
Eloi edited this page Jul 20, 2015 · 20 revisions

PushApi Documentation Analytics

Welcome to the PushApi wiki, here you will learn the basis of the PushApi project in which you are interested to.

Note: The API documentation is in the writing process and it is not fully documented at all yet.

Content

Introduction

The PushApi is a server side project using PHP. It provides a way to notify users of different kind of events. There is the possibility to send notifications using unicast (target user), multicast (interested group) or broadcast (all users).

It manages all the information related with notifications (users, events, groups, preferences...) and sends notifications when it is required.

Back to index

How does API work?

The basics

The API manages all the methods necessary in order to send a notification. Mainly, it organitzes the different data that is obtained from the agent and handles various operations in order to stay updated with users requirements. When it is required to send a notification, it stores the request and organitzes the data that must be send foreach destination and on backdoors there are some workers that are sending the messages.

It handles an internal database in order to manage the different data that is required for send notifications. If the website that is using the API has its own database, it should only add a new field into the users table in order to store the user id from the PushApi.

First steps

If you have installed the PushApi, you possibly don't know which are the following steps, here are the basic steps that you should take care:

  1. All the calls of the API need to be done with an app authentication and this can be done creating an app. The first step is create an app and get the information returned (now you can generate the authentication).

  2. The following step is to create themes. This will make you think which notifications you want to generate and what targets it will have (choose the correct range).

  • Unicast range to send to a user.
  • Multicast range to send to a group of users that are following a channel.
  • Broadcast range to send a notification to all users (i.e. newsletter).

  1. Create some channels. Each channel is a group of interested users that wants to receive notifications about that channel.

  2. Create users, that will force to add an email to the user because it is required for the registration. It can be added users massively sending various emails separated by comma.

With this steps you can now send notifications to unicast and broadcast themes because it is set, as default, that if users haven't set its preferences foreach theme, they will receive notifications for all the available devices.

Once the basic steps are done, it is recommended to finnish the database configuration:

  1. If it is known which channels each user wants to receive information, it can be created subscriptions for each one of them.

  2. Also if it is known users preferences.

  3. In order to have a better explanation of the mail subjects, it can be set the translations of the theme names. For each one it should be created a new subject.

Important for Android and iOs apps: when the app gets the registration id from their servers, they should send to the PushApi the new identifications or the notifications won't reach its targets.

Once all these steps are done, the API is correctly initialized. It can store the notifications with the send route. In order to send the stored notifications, workers should be running.

Back to index

Authentication

The app authentication is done via checking the request headers, a registered app must know its authentication values because it has the necessary data to generate the authentication key.

Once an app is created with a given name, the API returns the creation information with two new params (an app identification and a secret). When an agent wants to use the API it must send its authentication values in order to verify that it can use the system.

The authentication params must go via the request headers:

  • In a header named X-App-Id it should be stored the app id received from the creation of the app.
  • In a header named X-App-Auth it should be stored the app authentication generated.

The algorithm that generates the authentication key is a result of an MD5 encoding, it must be a string of the name of the app followed by the current date ('Y-m-d') and followed by the secret of the app (obtained when the app is created):

  • MD5('app_name' + 'Y-m-d' + 'app_secret')

Back to index

Get Android Key

To use the Android notifications it must be obtained an Android Key from the Google Cloud Platform.

  • Register or login.
  • Access into the Console and "Create Project" (choose the project name and create it). The project will be opened automatically.
  • Search and open the option APIs & auth -> APIs (find it into the left menu).
  • Search the Google Cloud Messaging for Android API and turn it on (just touching the OFF button).
  • Open the option APIs & auth -> Public API access and "Create new Key" from "Public API access". Choose the "Server Key" option (it is recommended to set the server IP for more security).
  • The APY KEY has been created.

Back to index

API routes

App

Route Method Params Description
/app POST name (string) Creates a new app that can use the API
/app/:id GET - Get the app $id information
/app/:id PUT name (string) Updates app information with the given one
/app/:id DELETE - Deletes the app $idApp
/apps GET - Retrives all the apps registered in the API

User

Route Method Params Description
/user POST email (string) Creates a new user or retrives the user if it was created before
/user/:id GET - Gets the given user
/user/:id PUT email (string), android_id (string), ios_id (string) Updates the user with the given information
/user/:id DELETE - Deletes the given user
/users GET - Retrives all the users registered
/users POST emails (emails sorted in a list separated by coma) Creates new users given its emails (only valid mails)
/user/:id/subscribe/:idchannel POST - Subscribes a user into a channel
/user/:id/subscribed/:idchannel GET - Gets the subscription of the user if it is subscribed before
/user/:id/subscribed/:idchannel DELETE - Deletes a user subscription
/user/:id/subscribed GET - Retrives all the subscriptions that user has subscribed
/user/:id/preference/:idtheme POST option (0, 1, 2, 3) Creates the preference that user wants to have set with a given theme
/user/:id/preference/:idtheme GET Gets the preference of the user if it has set it
/user/:id/preference/:idtheme PUT option (0, 1, 2, 3) Updates user preference with the given value
/user/:id/preference/:idtheme DELETE - Deletes a user preference
/user/:id/preferences GET Retrives all the preferences that user has set

Channel

Route Method Params Description
/channel POST name (string) Creates a new channel or retrives the channel if it was created before
/channel/:id GET - Get the given channel information
/channel/:id PUT name (string) Updates the channel information with the given one
/channel/:id DELETE - Deletes the given channel
/channels GET - Retrives all the channels registered
channel_name GET name Get the given channel information by name

Theme

Route Method Params Description
/theme POST name (string), range (unicast, multicast, broadcast) Creates a new theme or retrives the theme if it was created before
/theme/:id GET - Gets the given theme information
/theme/:id PUT range (unicast, multicast, broadcast) Updates the theme information with the given one
/theme/:id DELETE - Deletes the given theme
/themes GET - Retrives all the themes registered
/themes/range/:range GET - Retrives all the themes registered with the given :range
theme_name GET name Get the given theme information by name

Subject

Route Method Params Description
/subject POST theme_name (string), description (string) Creates a new subjector retrives the subjectif it was created before
/subject/:id GET - Get the given subject information
/subject/:id PUT theme_name (string), description (string) Updates the subjectinformation with the given one
/subject/:id DELETE - Deletes the given subject
/subjects GET - Retrives all the subjects registered

Send

Route Method Params Description
/send POST message (required), theme (required), user_id (optional), channel (optional), subject (optional), delay (optional, default 3600 seconds), time_to_live (optional, default 86400 seconds) Sends the notification to the target given its params

Back to index

Binary preferences

Why binary

It is used a bitmask in order to know which preferences the user has chosen. If you set one device per bit, when you have to check the option set by the user, you will only need to compare that option with the device mask.

For now, the PushApi only support 3 kind of target devices (emails, smartphones and chrome) so it is using 3 bits. In this case, it would be easy to know with an integer which option the user have set. The problem is, the more devices the PushApi supports, the more complexity to know in which devices the user wants to receive the Push.

Here are some examples in order to understand it:

  • With 2 devices you can remember the 4 integers of the preferences and you can know what preferences have set the user. In this case, the masks used are 01 and 10.
Mask Integer Target
00 0 none
01 1 email
10 2 smartphone
11 3 all devices
  • With 4 devices (a, b, c, d) there are 15 different options to be set and it would be harder to remember the integers, the easiest option you have is to set a list of constants in order to know the meaning of each number. Using a bitmap, you only have to remember the masks and the comparison with the option should be easier:
Mask Integer Target
0000 0 none
0001 1 a
0010 2 b
0100 4 c
1000 8 d
0101 5 only c and a
... ... ...
1101 1 only d, c and a
... ... ...
1111 1 all devices

Current bitmask

Here is the actual bitmask that PushApi is using:

Target Mask Integer
None 000 0
Email 001 1
Smartphones 010 2
Chrome 100 4
All devices 111 7

Back to index

Thank you!

Clone this wiki locally