Sending Push Notifications Using APNS

DreamFactory 2.5 includes support for Apple Push Notification Service (APNS). It is implemented as a native service of 
DreamFactory. Once you create an APN service in DreamFactory, you can use it as a proper push notification provider for 
your application.

DreamFactory APN service supports sending push notification to a single device using its device token. The service can 
also act as a push notification provider for your application by supporting device registration by your application. Here 
is an overview of how DreamFactory works as a push notification service provider.

# In DreamFactory you create an application for your iOS app. This application basically represents your iOS app in DreamFactory.
# When you create an application in DreamFactory you will get an API Key.
# Store this API Key in your iOS app.
# On your iOS app, when your user confirms to receive push notification for the app, you make a request to DreamFactory APN service providing the API Key and the user's device token.
# DreamFactory stores the device token under your API Key.
# When it's time to send push notification, you make a request to the DreamFactory APN service providing your notification message and the API Key.
# DreamFactory will send the message to all of your registered devices under that API Key.

=== Creating a DreamFactory APN Service ===

You can create an APN service from the admin console. Log in to the admin console and select the 'Services' tab. 
Click on the 'Create' button from the left menu. From the ''Service Type'' drop down menu select Notification -> Apple Push Notification. 
Enter all the service configuration information and save the form to create your service. For more details check [[DreamFactory/Features/Push_Notification_Services]].

=== API Endpoints  ===

==== Send push notification to all devices registered for your application ====

<pre>POST https://{url}/api/v2/{apn-service-name}/push?api_key={your-application-api-key}</pre>
Request body:
<source lang="JavaScript">
{
  "message": "string",
  "badge": 0,
  "sound": "string",
  "action-loc-key": "string",
  "loc-key": "string",
  "loc-args": [
    "string"
  ],
  "custom": [
    {}
  ]
}
</source>

Note: Only message is required in the body. You can also provide the API Key using the request header X-DreamFactory-Api-Key instead of the <code>api_key</code> query parameter.

==== Send push notification to a single device ====

<pre>POST https://{url}/api/v2/{apn-service-name}/push</pre>
Request body:
<source lang="JavaScript">
{
  "message": "string",
  "badge": 0,
  "sound": "string",
  "action-loc-key": "string",
  "loc-key": "string",
  "loc-args": [
    "string"
  ],
  "custom": [
    {}
  ],
  "device_token": "string"
}
</source>

Note: Only message and device_token is required in the body.

==== Register device tokens ====

<pre>POST https://{url}/api/v2/{apn-service-name}/register?api_key={your-application-api-key}</pre>
Request body:
<source lang="JavaScript">
{
  "device_token": "string"
}
</source>

Note: You can also provide the API Key using the request header X-DreamFactory-Api-Key instead of the <code>api_key</code> query parameter.

==== Replace existing device token ====

<pre>PUT https://{url}/api/v2/{apn-service-name}/register?api_key={your-application-api-key}</pre>
Request body:
<source lang="JavaScript">
{
  "old_token": "string",
  "new_token": "string"
}
</source>

Note: You can also provide the API Key using the request header X-DreamFactory-Api-Key instead of the <code>api_key</code> query parameter.

==== Delete all device tokens ====

<pre>DELETE https://{url}/api/v2/{apn-service-name}/register?api_key={your-application-api-key}</pre>

Note: You can also provide the API Key using the request header X-DreamFactory-Api-Key instead of the <code>api_key</code> query parameter.
Warning: This will delete all device tokens that are registered under your application. 

==== List all registered device tokens ====

<pre>GET https://{url}/api/v2/{apn-service-name}/register?api_key={your-application-api-key}</pre>

Note: You can also provide the API Key using the request header X-DreamFactory-Api-Key instead of the <code>api_key</code> query parameter.


=== Example - Sending push notification to all devices registered for your application ===

* Service name: apns
* Host: foo.com
* api_key = 123abc
* Request Content-Type: application/json
* Request body:
<pre>
    {
      "message": "Hello World!"
    }
</pre>
* Request URL:
<pre>POST https://foo.com/api/v2/apns/push?api_key=123abc</pre>

=== Example - Sending push notification to a single device ===

* Service name: apns
* Host: foo.com
* Request Content-Type: application/json
* Request body:
<pre>
    {
      "message": "Hello World!",
      "device_token": "123abc"
    }
</pre>
* Request URL:
<pre>POST https://foo.com/api/v2/apns/push</pre>

=== Example - Registering device token ===

* Service name: apns
* Host: foo.com
* api_key = 123abc
* Request Content-Type: application/json
* Request body:
<pre>
    {
      "device_token": "123abc"
    }
</pre>
* Request URL:
<pre>POST https://foo.com/api/v2/apns/register?api_key=123abc</pre>

=== Example - Replacing existing device token ===

* Service name: apns
* Host: foo.com
* api_key = 123abc
* Request Content-Type: application/json
* Request body:
<pre>
    {
      "old_token": "123abc ",
      "new_token": "456def"
    }
</pre>
* Request URL:
<pre>PUT https://foo.com/api/v2/apns/register?api_key=123abc</pre>

=== Example - Deleting device tokens by API Key ===

* Service name: apns
* Host: foo.com
* api_key = 123abc
* Request Content-Type: application/json
* Request URL:
<pre>DELETE https://foo.com/api/v2/apns/register?api_key=123abc</pre>

=== Example - Listing device tokens by API Key ===

* Service name: apns
* Host: foo.com
* api_key = 123abc
* Request Content-Type: application/json
* Request URL:
<pre>GET https://foo.com/api/v2/apns/register?api_key=123abc</pre>