-
Notifications
You must be signed in to change notification settings - Fork 9
Home
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.
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:
-
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).
-
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).
-
Create some channels. Each channel is a group of interested users that wants to receive notifications about that channel.
-
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:
-
If it is known which channels each user wants to receive information, it can be created subscriptions for each one of them.
-
Also if it is known users preferences.
-
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.
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')
| 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 |
| 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 |
| 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 |
| Route | Method | Params | Description |
|---|---|---|---|
| /theme | POST | 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 |
| /theme/range/:range | GET | - | Retrives all the themes registered with the given :range |
| 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 |
| Route | Method | Params | Description |
|---|---|---|---|
| /send | POST | message (required), theme (required), user_id (optional), channel (optional) | Sends the notification to the target given its params |
Thank you!