App API

Overview

This API documentation covers registration and deregistration of devices.

URL scheme: https://<customer-id>.push.delivery/push-api/<endpoint>

To use the service you need HTTP basic auth. Data is sent as JSON via POST.

REST Endpoints

reg

Subscribe device to a tag or multiple tags. Tags can be identified by ID or sourceID (externally assigned ID). Tags with sourceID’s are typically created from external services by accessing the push admin REST API. Either tagIds or tagSourceIds needs to be provided. Other tags the device might be already subscribed to are not affected by this call.

Table 1. Request Parameter Description
Name	Description	Example
tagId	The ID(s) of the tag	4
tagSourceId	The source ID(s) of the tag	sport_football_team_fcb_goal
appId	The ID of the app	30
appVersion	Optional: the Version of the app	V1.0.11.3b
platformId	The ID of the platform	3
deviceId	The ID generated by the device	b77b7f01bab316ad38d3…

Example URL

https://<customer-id>.push.delivery/push-api/reg

Example POST Request with tag ID (content type: application/json)

{
    "tagId": <id-number>,
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request with tag IDs (content type: application/json)

{
    "tagId": [<id-number>,<id-number>],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request with tag source ID (content type: application/json)

{
    "tagSourceId": "<id-string>",
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request with tag source IDs (content type: application/json)

{
    "tagSourceId": ["<id-string>","<id-string>"],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example Response (content type: text/plain)

OK

The response will always be "OK", even if invalid parameters are provided.

ureg

Unsubscribe device from tag(s). If no tag id or tag sourceId is provided, all existing tag subscriptions for this device will be removed.

Table 2. Request Parameter Description
Name	Description	Example
tagId	the ID(s) of the tag(s), if omitted and no tagSourceId(s) provided, all tags will be unregistered	4
tagSourceId	The source ID(s) of the tag(s)	sport_football_team_fcb_goal
appId	The ID of the app	30
platformId	The ID of the platform	3
deviceId	The ID generated by the device	b77b7f01bab316ad38d3…

Example URL

https://<customer-id>.push.delivery/push-api/ureg

Example POST Request with tag ID (content type: application/json)

{
    "tagId": <id-number>,
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request with tag IDs (content type: application/json)

{
    "tagId": [<id-number>,<id-number>],
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request with tag source ID (content type: application/json)

{
    "tagSourceId": "<id-string>",
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request with tag source IDs (content type: application/json)

{
    "tagSourceId": ["<id-string>","<id-string>"],
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request for complete unregistration (content type: application/json)

{
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example Response (content type: text/plain)

OK

The response will always be "OK", even if invalid parameters are provided.

list

List subscribed device tags. Source Id of tags is optional.

Table 3. Request Parameter Description
Name	Description	Example
appId	The ID of the app	4
platformId	The ID of the platform	30
deviceId	The ID generated by the device	b77b7f01bab316ad38d3…

Table 4. Response Parameter Description
Name	Description	Example
id	The ID of the tag	6
name	The name of the tag	Sport
sourceId	The source ID of the tag	sport_football_team_fcb_goal
tagOptionalParameters	Parameter map (optional)	{ "auto-subscribe": "true", "visible": "true" }

Example URL

https://<customer-id>.push.delivery/push-api/list

Example POST Request (content type: application/json)

{
    "appId": <id-number>,
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example Response (content type: application/json)

[
    {
      "id": <tag-id-number>,
      "sourceId" "<tag-id-string>",
      "name": "<tag-name>",
      "tagOptionalParameters":{
        "<optionalParameterMap-key-1>":"<optionalParameterMap-value-1>",
        "<optionalParameterMap-key-2>":"<optionalParameterMap-value-2>"
        ...
      }
    },
    {
      "id": <tag-id-number>,
      "name": "<tag-name>"
    }
]

tags

List available app tags. Tags are grouped. Tags and groups can both optionally have source IDs for external identification. Groups can have sub groups. Tags that are not in any group will appear in the response in the "default" group.

Table 5. Request Parameter Description
Name	Description	Example
appId	The ID of the app	30
platformId	The ID of the platform	4

Table 6. Response Parameter Description
Name	Description	Example
name	The name of the tag group	Sport
tags.id	The ID of the tag	6
tags.name	The name of the tag	Football goals
tags.sourceId	The source ID of the tag	sport_football_team_fcb_goal
tags.tagOptionalParameters	Parameter map (optional)	{ "auto-subscribe": "true", "visible": "true" }

Example URL with POST method

POST https://<customer-id>.push.delivery/push-api/tags

Example POST Request (content type: application/json)

{
    "appId": <id-number>,
    "platformId": <id-number>
}

Example URL with GET method

GET https://<customer-id>.push.delivery/push-api/v3/<customer-id>/tags/<app-id>

Example Response without source ID’s (content type: application/json)

[
    {
        "name" : "default",
        "tags" : [
            {
                "id": <tag-id-number>,
                "name": "<tag-name>",
                "tagOptionalParameters":{
                    "<optionalParameterMap-key-1>":"<optionalParameterMap-value-1>",
                    "<optionalParameterMap-key-2>":"<optionalParameterMap-value-2>"
                    ...
                }
            }
        ]
    },
    {
        "id" : <group-id-number>,
        "name" : "<group-name>",
        "tags" : [
           ...
        ],
        "groups" : [
            {
                "id" : <sub-group-id-number>,
                "name" : "<sub-group-name>",
                "tags" : [
                    ...
                ],
                "groups" : [
                    ...
                ]
            }
        ]
    }
]

Example Response with source ID’s (content type: application/json)

[
    {
        "id" : 0,
        "name" : "default",
        "tags" : [
            {
                "id": <tag-id-number>,
                "sourceId": "<tag-source-id-string>",
                "name": "<tag-name>"
            }
        ]
    },
    {
        "id" : <group-id-number>,
        "sourceId": "<group-source-id-string>",
        "name" : "<group-name>",
        "tags" : [
           ...
        ],
        "groups" : [
            {
                "id" : <sub-group-id-number>,
                "sourceId": "<sub-group-source-id-string>",
                "name" : "<sub-group-name>",
                "tags" : [
                    ...
                ],
                "groups" : [
                    ...
                ]
            }
        ]
    }
]

set

Set the subscriptions of a device to a tag or multiple tags. Tags can be identified by ID or sourceID (externally assigned ID). Tags with sourceID’s are typically created from external services by accessing the push admin REST API. Either tagIds or tagSourceIds needs to be provided. Each call will replace whatever subscriptions for this device existed before.

if no tags are provided, the request will be ignored. To unregister the device please use the '/ureg' endpoint.

Table 7. Request Parameter Description
Name	Description	Example
tagId	The ID(s) of the tag	4
tagSourceId	The source ID(s) of the tag	sport_football_team_fcb_goal
appId	The ID of the app	30
appVersion	Optional: the Version of the app	V1.0.11.3b
platformId	The ID of the platform	3
deviceId	The ID generated by the device	b77b7f01bab316ad38d3…

Example URL

https://<customer-id>.push.delivery/push-api/set

Example POST Request with tag ID (content type: application/json)

{
    "tagId": <id-number>,
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request with tag IDs (content type: application/json)

{
    "tagId": [<id-number>,<id-number>],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request with tag source ID (content type: application/json)

{
    "tagSourceId": "<id-string>",
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example POST Request with tag source IDs (content type: application/json)

{
    "tagSourceId": ["<id-string>","<id-string>"],
    "appId": <id-number>,
    "appVersion" : "<version-string>",
    "platformId": <id-number>,
    "deviceId": "<id-string>"
}

Example Response (content type: text/plain)

OK

The response will always be "OK", even if invalid parameters are provided.