User
The User is the main actor of the Push Api. All the system is turning arround him.
Push Api stores the basic information needed to send the notifications such as the email address and devices identifications.
Once an user is created, it is generated a unique ID in order to be stored in the external system that is using the Push API, this ID will be used with all calls that requires to refer an user so, it should be stored in your user database.
User contains more requests than the other calls and for this reason here are some shortcuts to improve user routes navitagion.
Routes
-
Basic User
-
Channel Subscription
-
Theme Preferences
/user
Creates a user with the given the email.
It is created with email in order to have some basic data. As all users have an email address, it can be used immediately after creating user to send notifications.
| Params | Type | Required? | Description |
|---|---|---|---|
| string | true | Email of the new user. |
Response
{
"result": {
"id": 1,
"email": [
1: "[email protected]"
],
"android": [],
"ios": []
}
}
Response keys description
- id is the value created by Push API to that user (unique and non mutable).
- email/android/ios are the device addresses that user have set. They are stored into an array. If user has not got values, the result value is an empty array.
- int: deviceId: the 'int' references the unique device identification by Push API (so it can be later deleted) and the 'deviceId' does not need explanation.
/user/:id
Gets all user :id data.
No params expected.
Response
{
"result": {
"id": 1,
"email": [
1: "[email protected]",
3: "[email protected]"
],
"android": [
5: "AAAAA-AA-SAMPLE-A-AAAA-AAAA-AAAA"
],
"ios": []
}
}
/user/:id
Deletes the given user :id.
Response
{
"result": true
}
/user/:id/device
Adds user :id devices.
- It can be updated only one value per param if it is set.
- It prevents to add duplicate values and updates smartphones device ids when a new user is using the same smartphone (it works only with smartphones ids).
| Params | Type | Required? | Description |
|---|---|---|---|
| string | false | Email of the new user. | |
| android | string | false | Android id of the user device. |
| ios | string | false | Ios id of the user device. |
Response
{
"result": {
"id": 1,
"email": [
1: "[email protected]",
3: "[email protected]"
],
"android": [
5: "AAAAA-AA-SAMPLE-A-AAAA-AAAA-AAAA"
],
"ios": []
}
}
/user/:id/device
Retrives user :id device unique id given its reference by param.
If the user does not have that reference, the response is false value.
| Params | Type | Required? | Description |
|---|---|---|---|
| reference | string | true | The device address identification. |
Response
Searching [email protected] unique id.
{
"result": {
"id": 10,
"type": "ios",
"user_id": 2,
"reference": "XXXXXXXX-SAMPLE-XXXX-XXXX-XXXXXXXXXXXX"
}
}
Responses
- If found, the result is the unique id.
- If not found, the result is boolean false.
/user/:id/device/:idDevice
Retrives user :id device unique id given its reference by param.
If the user does not have that device, the response is false value.
Response
{
"result": {
"id": 10,
"type": "ios",
"user_id": 2,
"reference": "XXXXXXXX-SAMPLE-XXXX-XXXX-XXXXXXXXXXXX"
}
}
/user/:id/device/:idDevice
Removes the device :idDevice from user :id.
Response
{
"result": true
}
/user/:id/device/type/:type
Removes all user devices given its type.
Email type cannot be removed, there must be always one email.
Response
{
"result": true
}
/user/:id/smartphones
Retrives the smartphones registered by user :id.
No params expected.
Response
{
"result": [
"Android"
]
}
/users
Creates new users given its emails.
Only users with valid mails will be created.
| Params | Type | Required? | Description |
|---|---|---|---|
| emails | Json | true | A Json array of the users emails that should be registered. I.e: ["[email protected]","[email protected]","[email protected]"] |
Response
{
"result": [
{
"id": 8,
"email": [
"[email protected]"
],
"android": [],
"ios": []
},
{
"id": 9,
"email": [
"[email protected]"
],
"android": [],
"ios": []
},
{
"id": 10,
"email": [
"[email protected]"
],
"android": [],
"ios": []
}
]
}
/users
Retrives all the users registered.
| Params | Type | Required? | Description |
|---|---|---|---|
| limit | string | false | Max results that must be displayed. |
| page | string | false | Page to start displaying results. |
Response
{
"result": {
"users": [
{
"id": 1,
"email": [
1: "[email protected]",
3: "[email protected]"
],
"android": [
5: "AAAAA-AA-SAMPLE-A-AAAA-AAAA-AAAA"
],
"ios": []
},
{
"id": 2,
"email": {
"6": "[email protected]"
},
"android": [],
"ios": []
},
{
"id": 3,
"email": {
"7": "[email protected]"
},
"android": [],
"ios": [
10: "XXXXXXXX-SAMPLE-XXXX-XXXX-XXXXXXXXXXXX"
]
}
],
"limit": 3,
"page": 1,
"totalInPage": 3
}
}
If it is being searched using pages, when the last page is reached the next page response will display an array of users key empty.
User Channel Subscriptions
Users that are interested in receive notifications of different channels should be first subscribed. A channel subscription is a symbolic link of the user id and the channel id.
/user/:id/subscribe/:idchannel
Subscribes a user :id with a channel :idchannel.
Response
{
"result": {
"user_id": 1,
"channel_id": 1,
"id": 1
}
}
/user/:id/subscribed/:idchannel
Gets the channel subscription of the user :id if exists the subscription.
No params expected.
Response
{
"result": {
"user_id": 1,
"channel_id": 1,
"id": 1
}
}
/user/:id/subscribed/:idchannel
Deletes a user :id channel subscription.
Response
{
"result": true
}
/user/:id/subscribed
Retrives all the subscriptions that user :id is subscribed.
No params expected.
Response
{
"result": [
{
"id": 1,
"user_id": 1,
"channel_id": 1
},
{
"id": 2,
"user_id": 1,
"channel_id": 2
}
]
}
User Theme Preferences
By default user will receive all notifications to all the devices that he has registered if he has not managed preferences before.
User can enable/disable notifications or choose to which device he wants to receive each notification or all of them.
/user/:id/preference/:idtheme
Creates the preference that user :id wants to have set with a given theme :idtheme..
| Params | Type | Required? | Description |
|---|---|---|---|
| option | integer (see mask values) | true | The mask value that distinguish between which device user wants to receive the notifications. |
Response
{
"result": {
"user_id": 1,
"theme_id": 1,
"option": "1",
"id": 1
}
}
/user/:id/preference/:idtheme
Gets the preference value of the user :id.
Response
{
"result": {
"user_id": 1,
"theme_id": 1,
"option": "1",
"id": 1
}
}
/user/:id/preference/:idtheme
Updates user preference with the given value
| Params | Type | Required? | Description |
|---|---|---|---|
| option | integer (see mask values) | true | The mask value that distinguish between which device user wants to receive the notifications. |
Response
{
"result": {
"user_id": 1,
"theme_id": 1,
"option": "3",
"id": 1
}
}
/user/:id/preference/:idtheme
Deletes a user :id preference.
Response
{
"result": true
}
/user/:id/preferences
Retrives all user :id the preferences of the user :id.
No params expected.
Response
{
"result": [
{
"id": 1,
"option": "1",
"user_id": 1,
"theme_id": 1
},
{
"id": 2,
"option": "0",
"user_id": 1,
"theme_id": 2
},
{
"id": 3,
"option": "1",
"user_id": 1,
"theme_id": 3
}
]
}
/user/:id/preferences
Updates all user preferences to the same option. It can enable/disable all or choose to which device wants to receive all the notifications.
| Params | Type | Required? | Description |
|---|---|---|---|
| option | integer (see mask values) | true | The mask value that distinguish between which device user wants to receive the notifications. |
Response
{
"result": true
}
Updated less than a minute ago