Mag+ Subscriptions API Specification - DRAFT

Introduction

This is an API specification that allows publishers to handle entitlements in-house and only leave the fulfillment part to the Mag+ system. This specification consists of two API calls: Publish issue and Get all entitlements.

These API calls must be implemented by the customer, i.e. the subscription provider. The URLs to the API endpoints are configurable via Mag+ Publish at http://publish.magplus.com/

Mag+ will automatically add a number of query parameters to each endpoint request (as specified later in this document). For POST requests the parameters will be sent as both url query parameters and in the POST body.

All requests must come over SSL/HTTPS, and have a valid api_key parameter.

The api_key for your brand can be found in the admin section of Mag+ Publish.

Note that the SSL certificate MUST be valid for the account view to work on the iPad.

The responses from the API must be in JSON format, and a successful API call must always return a 2xx HTTP response code. A response code other than 200/201 will be interpreted as a failure.

All requests have a hard timeout of 5000 ms, but under normal conditions your implementation of the API should never take more than 1000 ms.

API endpoints that the customer must implement

Publish issue

Responds to POST requests.

This endpoint is used to notify the publisher when a new issue is published using Mag+ Publish. Note that the optional external_issue_id parameter is configurable in Mag+ Publish on a per issue basis.

Parameters automatically sent from Mag+

• issue_id Mag+ Publish ID of the issue that was published
• publish_time ISO8601 UTC date in the format "YYYY-MM-DDThh:mm:ssZ"
• api_key Shared secret between Mag+ Publish and the customer
• external_issue_id (optional) Custom ID of the issue that was published

Successful response example

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 15
Connection: keep-alive

{"status":"OK"}

Error response example

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 28
Connection: keep-alive

{"error":"Invalid issue_id"}

Get all entitlements

Responds to GET requests.

This endpoint is used by the Mag+ API to retrieve all entitlements for a user (identified using the session_token parameter).

The list of entitlements should be Mag+ Publish issue_id's (The same ids that you got in the publish issue requests. They must be integers).

Parameters automatically sent from Mag+

• api_key Shared secret between Publish and the third party
• session_token The session token for the user
• device_id (optional) Device identifier

Successful response example

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 101
Connection: keep-alive

{"username":"kathy","entitlements":[1,2,3],"promotion":{"code":123,"message":"Promotional message!"}}

The username value is currently only used for logging purposes.

If the user has no entitlements then the list should be empty, not missing.

The promotion section is optional. When present it must contain both a code and a message.

Error response example

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 33
Connection: keep-alive

{"error":"Invalid session_token"}

Optional API endpoints

Download complete

Responds to POST requests.

This optional endpoint is used to notify the publisher when an issue has been downloaded.

Note that it is possible to track each user individual downloads via the session_token.

Parameters automatically sent from Mag+

• api_key Shared secret between Publish and the third party
• session_token The session token for the user
• issue_id Mag+ Publish ID of the issue that was downloaded
• device_id (optional) Device identifier

Successful response example

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 15
Connection: keep-alive

{"status":"OK"}

Error response example

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 28
Connection: keep-alive

{"error":"Invalid issue_id"}

Suggestions

We suggest that the returned session tokens are SHA-1 hashes or similar.

Activation

In order to activate the subscription API, the customer will go through the following steps in Mag+ Publish:

1. Activating Third Party Subscription API.
2. Specifying URLs to the implemented Subscription API endpoints.
3. Retrieving the assigned API key and using it for auhorization in the implemented Subscription API.

Testing of API implementations

There is a lint test for implementations of this API, it is available at https://magplus-subscriptions-api.herokuapp.com/test

This test interface allows the developer to validate responses from specified API endpoints. It might also help identify possible implementation issues.

Input parameters

The authentication parameters, passed along with the HTTP requests.

• api_key Shared secret between Mag+ Publish and the API
• session_token A valid session token for a user in the tested API

Endpoint URLs to be tested.

• entitlements_url (required) URL to the entitlements endpoint
• publish_issue_url URL to the publish issue endpoint
• my_account_view_url URL to the account web view (Integration Guide: 3.2 Webview Entry)
• download_complete_url URL to the download complete endpoint

Note that the entitlements_url is currently the only required URL for the test to run.