User Subscription

Create, modification, or view subscription records associated with a given user.

Create

Required Attributes

Example Request

POST /users/1/subscriptions HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "subscriptions",
    "attributes": {
      /* Both dates must be ISO-8601 */
      "dateEnded": "2015-01-01T12:00:00-05:00",
      "dateStarted": "2014-01-01T12:00:00-05:00",
      /* Optional: If included, must be a string. */
      "externalIdentifier": "MY-COMPANY-IDENTIFIER",
      /* One of: individual, free, site. */
      "license": "individual",
      /* One of: online, print, print-online */
      "resource": "online",
      "trial": false
    }
  }
}

Example Response

HTTP/1.1 201 Created
Location: https://api.epublishing.com/users/1/subscriptions/1
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "subscriptions",
    "id": "1",
    "attributes": {
      "dateEnded": "2015-01-01T12:00:00-05:00",
      "dateEnded": "2014-01-01T12:00:00-05:00",
      "externalIdentifier": "MY-COMPANY-IDENTIFIER",
      "license": "individual",
      "resource": "online",
      "trial": false
    }
  }
}

Creating a Subscription for a Product

Use the product relationship to associate the subscription with a specific subscription product. The product id can be found in the admin tools.

POST /users/1/subscriptions HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "subscriptions",
    "attributes": {
      /* Both dates must be ISO-8601 */
      "dateEnded": "2015-01-01T12:00:00-05:00",
      "dateEnded": "2014-01-01T12:00:00-05:00",
      /* Optional: If included, must be a string. */
      "externalIdentifier": "MY-COMPANY-IDENTIFIER",
      "trial": false
    },
    "relationships": {
      "product": {
        "data": { "type": 'products', id: "123" }
      }
    }
  }
}

Errors

400 Bad Request

Sending invalid JSON results in a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "title": "Problems parsing JSON"
    }
  ]
}

Sending the wrong type of JSON values results in a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "title": "Body must be a JSON object"
    }
  ]
}

422 Unprocessable Entity

Sending invalid fields results in a 422 Unprocessable Entity response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Attribute",
      "detail": "type is missing",
      "source": {
        "pointer": "/data/type",
      }
    }
  ]
}

Update

Example Request

PUT /users/1/subscriptions/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "subscriptions",
    "id": "1",
    "attributes": {
      "externalIdentifier": "MY-NEW-COMPANY-IDENTIFIER"
    }
  }
}

Example Response

HTTP/1.1 200 Success
Location: https://api.epublishing.com/users/1/subscriptions/1
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "subscriptions",
    "id": "1",
    "attributes": {
      "dateEnded": "2015-01-01T12:00:00-05:00",
      "dateEnded": "2014-01-01T12:00:00-05:00",
      "externalIdentifier": "MY-NEW-COMPANY-IDENTIFIER",
      "license": "individual",
      "resource": "online",
      "trial": false
    }
  }
}

Errors

Any validation failures during the update return the same type of error response as a "create" action.

Delete (Removing a Subscription)

Example Request

DELETE /users/1/subscriptions/1 HTTP/1.1

Example Response

HTTP/1.1 204 No Content

Expiring a Subscription

Example Request

PUT /users/1/subscriptions/1/expire HTTP/1.1

Example Response

HTTP/1.1 200 Success
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "subscriptions",
    "id": "1",
    "attributes": {
      "dateEnded": "2015-01-01T12:00:00-05:00",
      "dateEnded": "2016-01-01T12:00:00-05:00", /* Now */
      "externalIdentifier": "MY-NEW-COMPANY-IDENTIFIER",
      "license": "individual",
      "resource": "online",
      "trial": false,
      "expired": true,
    }
  }
}

Retrieval

Example Request

GET /users/1/subscriptions HTTP/1.1
Accept: application/vnd.api+json

Example Response

HTTP/1.1 200 Success
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "type": "subscriptions",
      "id": "1",
      "attributes": {
        "dateEnded": "2015-01-01T12:00:00-05:00",
        "dateEnded": "2014-01-01T12:00:00-05:00",
        "externalIdentifier": "MY-NEW-COMPANY-IDENTIFIER",
        "license": "individual",
        "resource": "online",
        "trial": false
      }
    }
  ]
}

Retrieval (Individual)

Example Request

GET /users/1/subscriptions/1 HTTP/1.1
Accept: application/vnd.api+json

Example Response

HTTP/1.1 200 Success
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "subscriptions",
    "id": "1",
    "attributes": {
      "dateEnded": "2015-01-01T12:00:00-05:00",
      "dateEnded": "2014-01-01T12:00:00-05:00",
      "externalIdentifier": "MY-NEW-COMPANY-IDENTIFIER",
      "license": "individual",
      "resource": "online",
      "trial": false
    }
  }
}