Looking for v1.0? The documentation is still available here.

See the changelog for major changes since v1.0.

• Introduction
  • Overview
  • Terminology
  • Overview
  • Sample code
• Outline
  • Resources
  • Verbs
  • Relations
  • URI Summary
• Resources
  • Service Description
  • Reader
  • Edition
  • Permission
  • Subscription
  • Subscription Period
  • Reader Login
  • Authorised Device
  • Authentication
  • Web Edition SSO Tokens
  • Targeted Notifications
  • Stored File
• Technical Details
  • Request Authentication
  • Exceptions
  • Request Media Types
  • Pagination
  • Dates
  • Booleans
  • Enumerations
• Example Sessions
  • Creating A New Reader
  • Finding An Edition
  • Creating And Updating A Permission
  • Updating A Reader
  • Finding All iDevice Enabled Publications
  • Finding A Subscription
  • Creating A Subscription Period
  • Resetting Authorised Devices
  • Authenticating A Reader

This Document outlines the web service interface provided by YUDU to enable management of readers, purchases and subscriptions for digital editions.

Access to the service requires a Yudu Publisher account with the "REST API" permission and a valid API token created through the Yudu Publisher interface.

The Yudu API uses the "Representational state transfer" (REST) architectural style. In particular, it applies the "hypermedia as the engine of application state" (HATEOAS) principle in the design of the resources. If you are not already familiar with these principles then we recommend reading REST in Practice as an introduction before diving further into the Yudu API.

The following terminology is used in this document:

• Reader - An end user that will be reading your digital editions
• Edition - A Yudu digital edition
• Permission - Refers to the granting of access to one edition for one reader
• Reader login - A particular instance of a reader accessing an edition
• Publication - A Yudu publication (also known as a "group")
• Subscription - A Yudu subscription
• Subscription period - Refers to the granting of access to a subscription for a time period
• Authorised device - A single device which has been used by a reader to access an edition
• Web Edition SSO token - A Single Sign-On (SSO) token valid for authentication for some set of (Web) Editions
• Node - The Yudu Publisher system is arranged into a hierarchy of nodes. For most users you won't need to worry about the node ID of your Readers, however if you would like to place them at different levels within your part of the hierarchy you can by specifying it.
• Stored file - A file stored in AWS S3, which is associated with a node

This service is arranged into resources, such as readers and their permissions. Each resource can be operated on by using different HTTP methods or verbs such as such as GET, POST, PUT, DELETE and OPTIONS.

All code samples can be found in the examples directory and each is accompanied by a README.md file which contains the documentation.

Please note that these examples generally do not represent best practices for implementing clients of the API. For example, as noted below, rather than using the URIs as described, you are encouraged to make use of the hypermedia present in the resources to navigate the API, decoupling your implementation from ours. Unless otherwise stated, these examples should be treated as proof-of-concepts only, and not as applications ready for production use.

A sample PHP application that shows the use of the API. In particular, this example is not extensively tested and does not handle every possible error case in a suitable manner for production use.

A sample GUI java application that can be used to build and send requests to our service.

A sample .NET console application that demonstrates how to build and send requests to our service.

A basic ruby command line tool to calculate the correct Base64 encoded HMAC SHA256 hash for any string and shared secret (see Request Authentication). This can be used to check that your signing method is creating the correct signature.

Resources are the objects you interact with through the service. Each resource is accessible by a unique URI and supports a number of operations (see Verbs). Examples of resources in this service are Readers, Editions and Subscriptions.

As well as URIs for individual resources, the API defines URIs for lists of resources. These URIs can be used to create new resources by appending them to the list, or search for resources with certain properties. We will often refer to these lists of resources as resources for convenience.

HTTP Methods or Verbs are the actions which can be used on each resource. There are 5 verbs supported by this API:

• GET - Retrieve the current representation of a resource.
• POST - Create a new resource.
• PUT - Update an existing resource.
• DELETE - Delete an existing resource.
• OPTIONS - Get a list of verbs which are supported by the given resource.

Relations or Link Relations provide a way to navigate this service. Each XML representation of a resource will contain a number of links which reference other URIs. These URIs indicate the logical next steps when using this system.

Resource representations returned by this service may contain a links element which contains a list of link elements detailing a link to another resource or list of resources. They are represented in XML as follows:

  <link rel="http://schema.yudu.com/editions" name="editions"
    href="https://api.yudu.com/Yudu/services/2.0/editions/?reader=1234"
    type="application/vnd.yudu+xml"/>

The attributes of the link element are:

• rel - The relation. This identifies the resource being accessed as documented for each resource in Resources.
• name - The name of the relation. This is often the name of the linked resource is too but can convey different information, such as in links used for pagination or Get requests to resource lists.
• href - The URI of the linked resource.
• type - The content type of the representation of the resource.

In order to determine which verbs can be used to interact with a resource, it is recommended to make an OPTIONS request to the URI given in the link relation. This will return an Allow header containing a comma-separated list of allowed verbs.

The following table summarises all the available resource URIs, and the effect of each verb on them. Each of them is relative to the base URI for our API: https://api.yudu.com/Yudu/services/2.0.

This section describes the various resources accessible within this API, their XML representations, the verbs that can be used to interact with them, and the relations they define. All unqualified URIs given throughout this section are relative to the base URI for our API: https://api.yudu.com/Yudu/services/2.0.

The XML representations of the resources have some common features:

• Resource elements contains an id attribute which corresponds to the ID in the URI for the resource.
• Resource elements contains a links element which contains a list of link elements defining the relations for the resource.

The XML representations of the lists of resources also have some common features:

• The root element of a list of resources representation contains "pagination" attributes. See Pagination for details.
• The root element contains a {resourceName}List element which itself contains a list of resource representations.
• The root element contains a links element which contains a list of link elements for navigating the list if it has been paginated.

Further, the root element of any XML returned from or sent to the server must contain the namespace attribute: xmlns="http://schema.yudu.com"

In the XML descriptions of each resource the link elements within the links elements have been omitted for brevity. Similarly the returned resource representations within the {resourceName}List elements in a list representation have been omitted.

While not technically a resource this endpoint is the starting point for any interaction with the API. It is assumed that a user of the API does not know how to construct the URIs for any resource or the IDs or URIs of any existing resource. Instead a user starts at the service description and follows links to navigate the resource.

The service description is represented in XML as a root service tag with a single links tag containing the links for all the lists of resources.

<service xmlns="http://schema.yudu.com">
    <links>
      ⋮ // some link elements
    </links>
</service>

A GET request returns the XML representation of the service: a list of links to the other available URIs in the service.

The reader corresponds to a "Subscriber" in Yudu Publisher.

<reader xmlns="http://schema.yudu.com" id="1234">
  <username>example</username>
  <emailAddress>[email protected]</emailAddress>
  <firstName>Example</firstName>
  <lastName>User</lastName>
  <nodeId>1234</nodeId>
  <password>userPassword</password>
  <authorisedDeviceLimit>3</authorisedDeviceLimit>
  <links>
    ⋮ // some link elements
  </links>
</reader>

Note: The password field can be included by the user to update the password but will not be returned by the service.

<readers xmlns="http://schema.yudu.com" limit="100" offset="0" total="1293" truncated="true">
  <readerList>
    ⋮ // some reader elements
  </readerList>
  <links>
    ⋮ // some link elements
  </links>
</readers>

Readers can be sorted by the following fields (see Pagination for details):

• id
• node
• emailAddress
• username
• firstName
• lastName

A GET request returns the XML representation of a list of readers, optionally filtered using the following query string parameters, as well as the pagination parameters described in Pagination.

A POST request creates a new reader. The request body must contain the XML representation of a reader with the required fields as detailed in Permissible Fields.

A successful POST will result in a 201 CREATED response with a Location header specifying the URI of the newly created resource and the response body will contain the XML representation of the resource (including the id and links).

A GET request returns the XML representation of the reader. Note that any fields which do not have a value may not be included in the XML representation.

A PUT request updates an existing reader. The request body must contain the XML representation of a reader with the required fields as detailed in Permissible Fields. Of the fields marked "Allowed", only those which you wish to update should be included.

A DELETE request deletes an existing reader.

The edition corresponds to an "Edition" in Yudu Publisher.

<edition xmlns="http://schema.yudu.com" id="1234">
  <name>My Edition</name>
  <publishedDate>2014-01-01T00:00:00Z</publishedDate>
  <flashLiveUrl>http://hosted.edition.domain/pathToEditionFlashUrl</flashLiveUrl>
  <webLiveUrl>http://hosted.edition.domain/pathToEditionWebUrl</webLiveUrl>
  <htmlLiveUrl>http://hosted.edition.domain/pathToEditionHtmlUrl</htmlLiveUrl>
  <onDeviceName>My Edition</onDeviceName>
  <image_url>http://hosted.image.domain/pathToThumbnailUrl</image_url>
  <links>
    ⋮ // some link elements
  </links>
</edition>

<editions xmlns="http://schema.yudu.com" limit="100" offset="0" total="1293" truncated="true">
  <editionList>
    ⋮ // some edition elements
  </editionList>
  <links>
    ⋮ // some link elements
  </links>
</editions>

Editions can be sorted by the following fields (see Pagination for details):

• id
• name
• publishedDate

A GET request returns the XML representation of a list of editions, optionally filtered using the following query string parameters, as well as the pagination parameters described in Pagination.

A GET request returns the XML representation of the edition. Note that any fields which do not have a value may not be included in the XML representation.

The permission corresponds to an "Edition Permission" in Yudu Publisher.

<permission xmlns="http://schema.yudu.com" id="1234">
  <reader id="567"/>
  <edition id="890"/>
  <creationDate>2014-01-01T00:00:00Z</creationDate>
  <expiryDate>2014-06-01T00:00:00Z</expiryDate>
  <links>
    ⋮ // some link elements
  </links>
</permission>

<permissions xmlns="http://schema.yudu.com" limit="100" offset="0" total="1293" truncated="true">
  <permissionList>
    ⋮ // some permission elements
  </permissionList>
  <links>
    ⋮ // some link elements
  </links>
</permissions>

Permissions can be sorted by the following fields (see Pagination for details):

• id
• reader
• edition
• creationDate
• expiryDate

A GET request returns the XML representation of a list of permissions, optionally filtered using the following query string parameters, as well as the pagination parameters described in Pagination.

A POST request creates a new permission. The request body must contain the XML representation of a permission with the required fields as detailed in Permissible Fields.

A successful POST will result in a 201 CREATED response with a Location header specifying the URI of the newly created resource and the response body will contain the XML representation of the resource (including the id and links).

A GET request returns the XML representation of the permission. Note that any fields which do not have a value may not be included in the XML representation.

A PUT request updates an existing permission. The request body must contain the XML representation of a permission with the required fields as detailed in Permissible Fields.

A DELETE request deletes an existing permission.

The subscription corresponds to a "Subscription" in Yudu Publisher.

<subscription xmlns="http://schema.yudu.com" id="1234">
  <title>My Subscription</title>
  <onDeviceTitle>On Device Subscription Name</onDeviceTitle>
  <subscriptionType>flash_node</subscriptionType>
  <disabled>false</disabled>
  <defaultAuthorisedDeviceLimit>6</defaultAuthorisedDeviceLimit>
  <nodeId>567</nodeId>
  <links>
    ⋮ // some link elements
  </links>
</subscription>

<subscriptions xmlns="http://schema.yudu.com" limit="100" offset="0" total="1293" truncated="true">
  <subscriptionList>
    ⋮ // some subscription elements
  </subscriptionList>
  <links>
    ⋮ // some link elements
  </links>
</subscriptions>

Subscriptions can be sorted by the following fields (see Pagination for details):

• id
• title
• onDeviceTitle
• disabled
• subscriptionType
• node

A GET request returns the XML representation of a list of subscriptions, optionally filtered using the following query string parameters, as well as the pagination parameters described in Pagination.

A GET request returns the XML representation of the subscription. Note that any fields which do not have a value may not be included in the XML representation.

The subscription period corresponds to a "Subscription Period" in Yudu Publisher.

<subscriptionPeriod xmlns="http://schema.yudu.com" id="1234">
  <reader id="567"/>
  <subscription id="890"/>
  <startDate>2014-01-01T00:00:00Z</startDate>
  <expiryDate>2014-06-01T00:00:00Z</expiryDate>
  <links>
    ⋮ // some link elements
  </links>
</subscriptionPeriod>

<subscriptionPeriods xmlns="http://schema.yudu.com" limit="100" offset="0" total="1293" truncated="true">
  <subscriptionPeriodList>
    ⋮ // some subscriptionPeriod elements
  </subscriptionPeriodList>
  <links>
    ⋮ // some link elements
  </links>
</subscriptionPeriods>

Subscription periods can be sorted by the following fields (see Pagination for details):

• id
• reader
• subscription
• startDate
• expiryDate

A GET request returns the XML representation of a list of subscriptionPeriods, optionally filtered using the following query string parameters, as well as the pagination parameters described in Pagination.

A POST request creates a new subscription period. The request body must contain the XML representation of a subscription period with the required fields as detailed in Permissible Fields.

A successful POST will result in a 201 CREATED response with a Location header specifying the URI of the newly created resource and the repsonse body will contain the XML representation of the resource (including the id and links).

A GET request returns the XML representation of the permission. Note that any fields which do not have a value may not be included in the XML representation.

A PUT request updates an existing subscription period. The request body must contain the XML representation of a subscription period with the required fields as detailed in Permissible Fields.

A DELETE request deletes an existing subscription period.

The reader login represents a single login of a reader into an edition or app.

<readerLogin xmlns="http://schema.yudu.com" id="1234">
  <loginDate>2014-01-01T00:00:00Z</loginDate>
  <reader id="567"/>
  <node id="890"/>
  <platform>flash</platform>
  <emailAddress>[email protected]</emailAddress>
  <links>
    ⋮ // some link elements
  </links>
</subscription>

<readerLogins xmlns="http://schema.yudu.com" limit="100" offset="0" total="1293" truncated="true">
  <readerLoginList>
    ⋮ // some readerLogin elements
  </readerLoginList>
  <links>
    ⋮ // some link elements
  </links>
</readerLogins>

Reader logins can be sorted by the following fields (see Pagination for details):

• id
• reader
• node
• loginDate
• platform
• emailAddress

A GET request returns the XML representation of a list of reader logins, optionally filtered using the following query string parameters, as well as the pagination parameters described in Pagination.

A GET request returns the XML representation of the reader login. Note that any fields which do not have a value may not be included in the XML representation.

The publication corresponds to a "Group" in Yudu Publisher.

<publication xmlns="http://schema.yudu.com" id="1234">
  <name>A Publication</name>
  <iDeviceEnabled>true</iDeviceEnabled>
  <androidEnabled>false</androidEnabled>
  <links>
    ⋮ // some link elements
  </links>
</publication>

<publications xmlns="http://schema.yudu.com" limit="100" offset="0" total="1293" truncated="true">
  <publicationList>
    ⋮ // some publication elements
  </publicationList>
  <links>
    ⋮ // some link elements
  </links>
</publications>

Publications can be sorted by the following fields (see Pagination for details):

• id
• name
• iDeviceEnabled
• androidEnabled

A GET request returns the XML representation of a list of publications, optionally filtered using the following query string parameters, as well as the pagination parameters described in Pagination.

A GET request returns the XML representation of the publication. Note that any fields which do not have a value may not be included in the XML representation.

An authorised device represents a unique device which a reader has used to log in to an edition or app. Note that this resource is a subresource of reader so a reader ID is required in the URI.

Authorised devices have no XML representation as the only permitted verb is DELETE on the list resource.

A DELETE request removes all authorised devices from a reader. The purpose of this request is to effectively reset the "authorised device count" of a reader.

The authentication resource allows a user to authenticate a given reader's password. Note that this resource is a sub-resource of reader so a reader ID is required in the URI.

<authentication xmlns="http://schema.yudu.com">
  <password>userPassword</password>
  <authenticated>true</authenticated>
</authentication>

Note: The password field must be included by the user to authenticate a reader but will not be returned by the service.

A PUT request authenticates a reader.. The request body must contain the XML representation of an authentication with the required fields as detailed in Permissible Fields.

The token resource allows a third party to generate a short-lifetime SSO token that can be passed to a Web Edition for user authentication without a login dialog. Note that multiple tiers of authorisation are available, meaning this resource is additionally available as a sub-resource of other resources. It requires a unique User ID for whom to generate the token.

<authToken xmlns="http://schema.yudu.com">
    <key>uniqueUserIdentification</key>
    <tokenValue>0123456789abcdefghijklmnopqrstu</tokenValue>
    <validity>Single edition</validity>
</authToken>

A POST request creates an authentication token for the specified User ID. The request body must contain the XML representation of an authentication with the required fields as detailed in Permissible Fields. The response body will contain the generated token value, as well as a human-readable description of the authorisation level granted for the token.

This URI will generate tokens that will authenticate for any edition available in your Edition List.

A POST request creates an authentication token for the specified User ID. The request body must contain the XML representation of an authentication with the required fields as detailed in Permissible Fields. The response body will contain the generated token value, as well as a human-readable description of the authorisation level granted for the token.

This URI will generate tokens that will authenticate for all editions under the Publication specified in the URI.

A POST request creates an authentication token for the specified User ID. The request body must contain the XML representation of an authentication with the required fields as detailed in Permissible Fields. The response body will contain the generated token value, as well as a human-readable description of the authorisation level granted for the token.

This URI will generate tokens that will only authenticate for the Edition specified in the URI.

Given a User ID, the token resources generate a token value that, when used in combination with the ID, will authenticate a reader. Currently, these token values can only be passed directly to an edition by means of the edition's URL. By inserting both the ID and the token value into the URL as query parameters, the edition can be authenticated without requiring interaction by the reader.

In order to improve the seamless experience for your users, when a token generated by this API is used to authenticate a reader, the server will automatically provide that reader with another token. This new token will continue to authenticate the reader for future visits for the rest of that day. This token will be stored in the browser's local storage and so will be available for any visit from the same device and browser. However, should token details be provided in the URL your reader follows, these will take precedence over any locally-stored token.

Note that since these tokens have a limited lifetime, if a user does attempt to reuse a URL with a token after the token has expired, they may be presented with a login screen as other users would be. If the intention is to provide users with a seamless experience, then fresh URLs may need to be generated for them frequently, and they should be alerted to the limited lifetime of the URLs thus generated. A token-less URL may be intentionally provided to allow users to use locally-stored token details.

To successfully authenticate an edition using the token details, the following query parameters should be specified:

For example, if your edition URL is http://hosted.edition.domain/path/to/edition/index.html then the token above could be used by directing the user to the destination http://hosted.edition.domain/path/to/edition/index.html?yuduAuthId=uniqueUserIdentification&yuduAuthToken=0123456789abcdefghijklmnopqrstu. A simple use-case could be as follows:

1. A reader clicks on a link on your webpage indicating they wish to view an edition.
2. Your server reacts to that request by:
   1. sending a request to this API for a token for that user
   2. retrieving the token value from the response
   3. inserting the token value and user ID into the edition's target URL
   4. returning a 303 redirect with the modified edition URI as the target
3. The reader's browser redirects to the edition and the edition uses the token to authenticate.

A targeted notification represents a notification to be sent to a specified list of Yudu subscribers and/or third-party subscribers, via Firebase and APNS.

The targeted notification resource is different to other resources within the REST API, in that it doesn't represent an object of some kind, and therefore cannot be specified by an id. In addition to this, it never contains link elements defining relations of the resource and there are no pagination options necessary.

In addition to the "REST API" account permission, the "Send Custom Notifications" permission is also required for sending targeted notifications.

The targeted notification resource is represented in XML with a targetedNotification root element.

<targetedNotification xmlns="http://schema.yudu.com">
    <nodeId>1234</nodeId>
    <message>Notification body</message>
    <title>Notification title</title>
    <notificationPriority>DEFAULT</notificationPriority>
	<disableSound>false</disableSound>
	<iDeviceDeepLink>myapp://mylink</iDeviceDeepLink>
	<androidDeepLink>myapp://mylink</androidDeepLink>
    <subscribers>
        <thirdPartySubscriberToken>abcdef</thirdPartySubscriberToken>
        <subscriberUsername>abcdef</subscriberUsername>
    </subscribers>
</targetedNotification>

The notificationPriority enumeration represents the priority of the notification being sent. The permissible values are:

• DEFAULT
• HIGH

Please note that high priority notifications must be enabled at the publication for this to take effect. If no priority is specified or high priority notifications are not enabled, a notification with default priority will be sent.

The subscribers element can contain multiple third party subscribers and/or Yudu subscribers, but must contain at minimum one of either.

The priorities in iOS are differentiated by the sounds which are used thus disabling the sound would make the priority selected redundant.

The deep links that are currently supported are:

• <appScheme>://pageLink/editionId/<editionId>/ - to navigate to the given edition
• <appScheme>://pageLink/editionId/<editionId>/pageNumber/<pageNumber>/ - to navigate to the given edition at the given page number
• <appScheme>://latest-edition/ - to navigate to the latest edition
• <appScheme>://<tabName> - to navigate to the given tab. Note that the names of the default tabs are the same as those used for setting up the order of the tabs, while the names of the custom tabs are the same as those used in the custom tabs settings, with no whitespace if using multiple words.

A POST request sends a targeted notification to the specified list of subscribers, and returns an XML representation of the response.

A targeted notification response will be returned as an XML representation, providing information about the success of iOS push notifications and Firebase cloud messages, and reasons for failures.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<targetedNotificationResponse xmlns="http://schema.yudu.com">
    <firebaseResponse>
        <allSucceeded>false</allSucceeded>
        <responseMessage>
            Firebase certificate details are missing for this node.
            Please ensure the Firebase private key has been uploaded and selected,
            and the project ID supplied on the "editPublication.htm" page.
        </responseMessage>
    </firebaseResponse>
    <iOSResponse>
        <allSucceeded>false</allSucceeded>
        <responseMessage>
            Push notification certificate details are missing for this node.
            Please ensure the APNS security certificate has been uploaded and selected,
            and the password supplied on the "editPublication.htm" page.
        </responseMessage>
    </iOSResponse>
</targetedNotificationResponse>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<targetedNotificationResponse xmlns="http://schema.yudu.com">
    <firebaseResponse>
        <allSucceeded>true</allSucceeded>
        <responseMessage>
            Successfully completed sending Firebase messages.
            There were 1 messages to send, and 1 sent successfully.
        </responseMessage>
    </firebaseResponse>
    <iOSResponse>
        <allSucceeded>true</allSucceeded>
        <responseMessage>
            Completed sending iOS push notifications.
            There were 1 messages to send, and 1 sent successfully.
        </responseMessage>
    </iOSResponse>
</targetedNotificationResponse>

A stored file represents a file which is associated with a node and which is stored in AWS S3.

<supportedFileUsage name="SOME_FILE_USAGE">
    <fileTypeList>
        <fileType>.someExtension</fileType>
        <fileType>.someOtherExtension</fileType>
    </fileTypeList>
</supportedFileUsage>

Note: The file type list can consist of one or more elements.

<storedFiles xmlns="http://schema.yudu.com">
    <supportedFileUsageList>
        // some supported file usage elements
    </supportedFileUsageList>
    <links>
        <link rel="http://schema.yudu.com/storedFiles" name="storedFiles"
              href="https://api.yudu.com/Yudu/services/2.0/nodes/<the_given_node>/storedFiles" type="application/vnd.yudu+xml"/>
    </links>
</storedFiles>

This section refers to the fields relevant to the main stored files requests, not the supported file usages request.

A GET request returns the XML representation of a list of supported file usages.

A PUT request uploads a file at the specified node. It must be a multipart request with a multipart/form-data Content-Type. The body must contain the required field file as mentioned in Permissible Fields. If the usage field is missing, it defaults to NOT_SPECIFIED. A full list of file usages supported at a given node can be obtained via the Supported File Usage List request. If a file is uploaded with the same name and the same usage as an existing file, it replaces the original.

A successful PUT will result in a 200 OK response except for uploading a PDF file with a NOT_SPECIFIED usage which results in a 201 ACCEPTED response, as the file is processed asynchronously.

If a request fails, the response body will contain an XML representation of the error, including the code, customError (if relevant), and detail elements, as illustrated in the example below.

<error xmlns="http://schema.yudu.com">
  <code>CLIENT_ERROR</code>
  <customError>1001</customError>
  <detail>This file is empty. Please upload a valid file.</detail>
</error>

See the following table for more information about errors.

Each request must be accompanied by a two piece authentication scheme. To access the service a key and shared secret must be used. These can be obtained and managed through the Yudu Publisher interface. The key is used for identification and the shared secret is used to sign each request. Both the key and signature should be included in specific request headers.

The API key must be supplied with each request as a request header called Authentication.

The query parameters in the URI of each request must include timestamp - a unix epoch timestamp (in seconds) of the request. The timestamp is checked on our server to protect against replay attacks. You must make sure your server time is set accurately otherwise your requests may be rejected.

The shared secret should be used as the signing token used to generate a base-64 encoded HMAC-SHA256 hash of a specific string.

The signed string is constructed from the following parts:

1. The HTTP method of the request, in upper case. (e.g. PUT)
2. The absolute path of the service URI (e.g. /Yudu/services/2.0/permissions/)
3. The query string of the URI, including a timestamp parameter as detailed above, before they have been URL encoded, and sorted alphabetically (e.g. ?edition=123&reader=456&timestamp=1234567890 or [email protected]&timestamp=1234567890)
4. The full body of the request if appropriate - for PUT and POST requests - including whitespace if the body includes whitespace (e.g. <permission xmlns="http://schema.yudu.com" id="1234"><expiryDate>2014-06-01T00:00:00Z</expiryDate></permission>)

When making a GET request to the following URI and query string:

http://api.yudu.com/Yudu/services/2.0/permissions/?timestamp=1234567890&reader=1234

you should generate the HMAC using the string

GET/Yudu/services/2.0/permissions/?reader=1234&timestamp=123456789

When making a POST request to the following URI and query string:

http://api.yudu.com/Yudu/services/2.0/subscriptionPeriod/?timestamp=1234567890

and with the post data:

<subscriptionPeriod xmlns="http://schema.yudu.com">
  <reader id="1234"/>
  <subscription id="5678"/>
  <startDate>2014-01-01T00:00:00Z</startDate>
</subscriptionPeriod>

you should generate the HMAC using the string

POST/Yudu/services/2.0/permissions/?reader=1234&timestamp=123456789<subscriptionPeriod xmlns="http://schema.yudu.com">
  <reader id="1234"/>
  <subscription id="5678"/>
  <startDate>2014-01-01T00:00:00Z</startDate>
</subscriptionPeriod>

Note that the whitespace, including line breaks, is included in the signed string.

Errors will be signified by the using the relevant HTTP Status Code. For example "405 Method Not Allowed" if you attempt to PUT to a resource that does not support it, or "400 Bad Request" if the request was not valid. Many errors will have a response body containing an XML document describing the error in detail.

<error xmlns="http://schema.yudu.com">
  <code>VALIDATION_FAILURE</code>
  <detail>Validation failed: Username is already in use</detail>
  <validationFailures>
    <failure>
      <cause>DUPLICATE_USERNAME</cause>
      <field>username</field>
    </failure>
    <failure>
      <cause>NULL</cause>
      <field>password</field>
    </failure>
  </validationFailures>
</error>

All error representations will contain the code and detail elements. Only errors with the code VALIDATION_FAILURE will contain the validationFailures element.

In addition to standard HTTP status codes the service returns a descriptive code in the code element. The possible values are:

• NOT_FOUND - The resource could not be found.
• DUPLICATE_ITEM - The resource already exists.
• AUTHENTICATION_FAILURE - The authentication credentials were not correct.
• VALIDATION_FAILURE - The XML in the request body was invalid.
• UNKNOWN_ERROR - An unknown error occurred.
• CLIENT_ERROR - A bad request has been sent by the client.
• SERVER_ERROR - An unknown internal error occurred.

The media type of all communications with the server should be of the form application/vnd.yudu+xml. Thus this type should always be included in an appropriate Accept header, and when necessary, specified as the type of any POST data. Please see the Example Sessions to see how this should affect the requests you send. If you encounter an HTTP 406 status code, or a "Not Acceptable" error message without any further details, please check you have included this header in your request.

The response to a GET request to a list of resources is paginated. By default the resulting XML contains at all the resources if there are less than 100 and truncated the results to 100 if there are more.

The root element of a list of resources representation contains the following pagination attributes:

• limit - The number of resource representations returned in this request.
• offset - The offset from the first resource in the list.
• total - The total number of resources in the list.
• truncated - A boolean value whose value is false if all editions in the list have been returned in this response and true otherwise.

It is possible to set limit, offset and sort query parameters in order to access other resources.

The limit query parameter can be set to change the number of resources returned. The limit parameter must be between 1 and 1000 inclusive.

The offset query parameter can be set to request resources starting at a particular offset from the start. The offset parameter cannot be less than 0. This allows the client to access all the resources available by making multiple requests with a different offset. If the offset value is greater than the total, no resources will be returned. If the sum of the offset and limit is greater than the total, less resources than the limit will be returned.

For example, we could make one request with offset=0 to obtain the first 100 items and offset=100 to obtain the next 100 items, and so on.

The sort query parameter allows the client to choose the order in which the resources are returned. The sort parameter value is an ordered comma separated list of attribute names concatenated with _asc or _desc to signify whether the results should be sorted by that attribute in ascending or descending order. Each resource defined above is accompanied by list of permissible sort attributes names.

For example, suppose we wanted to list editions sorted first by name (ascending) and then by official publication date (descending). That is, we wish for the editions be sorted by the name, and for any two editions with the same name will be sorted with the latest publication date first. In this case we would use the following query parameter:

sort=name_asc,publishedDate_desc

Note that the order of the attributes is important. We must include the name_asc part first to ensure that this is the primary sort criteria.

The list representations contain a links element just like the singular resource representations. If the list is truncated several links may be available for navigating the paginated list.

The next link will be available if there are more resources accessible by increasing the offset parameter. The link relation is the list resource, the name is next and the href will have the same limit and sort parameters and an adjusted offset parameter to obtain the next resources.

The previous link will be available if there are more resources accessible by decreasing the offset parameter. The link relation is the list resource, the name is previous and the href will have the same limit and sort parameters and an adjusted offset parameter to obtain the previous resources. Note that since the offset cannot be less than 0, if offset is less than limit, following the previous link may result in some of the same resources being presented as are available on the current page.

Date parameters are used throughout this API, both in XML and in the URI query strings. All dates must be given in ISO 8601 format.

Boolean parameters are used throughout this API, both in XML and in URI query strings.

• In XML documents the only strings permissible as boolean values are true and false.
• In XML returned by the server, the strings true and false will be used to specify boolean values.
• In query strings the following boolean pairs are accepted:
  • true and false
  • t and f
  • yes and no
  • y and n
  • 1 and 0

Certain fields of the resource representations are enumerations. That is, there are a set number of permissible string values for the field. Such enumerations and their values are listed here.

The subscriptionType enumeration represents the type of subscription which is chosen when the subscription is created in Yudu Publisher. The permissible values are as follows:

• ios - iOS subscription
• ios_club - iOS club subscription
• ios_node - iOS node subscription
• android - Android subscription
• android_club - Android club subscription
• android_node - Android node subscription
• flash - Flash subscription
• flash_club - Flash club subscription
• flash_node - Flash node subscription
• universal - Universal subscription
• universal_club - Universal club subscription

The platform enumeration represents a device or platform type. The permissible values are as follows:

• flash - a web based app (flash or HTML5)
• air - an air based app (Android or Desktop)
• idevice - an iOS based app
• unknown - platform could not be determined

We wish to create a new reader at the node "1234". Request the base URI, which provides links to the other resources:

//Request
GET /Yudu/services/2.0/?timestamp=1412586000 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: YmYtVK8Se2GuFNlGNsRoiBT1WApfF85pPMVETI/FkFo=

//Response
HTTP/1.1 200 OK
Date: Mon, 06 Oct 2014 10:00:00 GMT
Content-Type: application/vnd.yudu+xml

<service xmlns="http://schema.yudu.com">
  <links>
    <link rel="http://schema.yudu.com/permissions" name="permissions"
          href="https://api.yudu.com/Yudu/services/2.0/permissions"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/readerLogins" name="readerLogins"
          href="https://api.yudu.com/Yudu/services/2.0/readerLogins"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/subscriptions" name="subscriptions"
          href="https://api.yudu.com/Yudu/services/2.0/subscriptions"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/readers" name="readers"
          href="https://api.yudu.com/Yudu/services/2.0/readers"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/editions" name="editions"
          href="https://api.yudu.com/Yudu/services/2.0/editions"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/publications" name="publications"
          href="https://api.yudu.com/Yudu/services/2.0/publications"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/subscriptionPeriods" name="subscriptionPeriods"
          href="https://api.yudu.com/Yudu/services/2.0/subscriptionPeriods"
          type="application/vnd.yudu+xml"/>
  </links>
</service>

This tells us that there are seven links, with the relations defined as above.

We want to create a new reader, and we know from the link relations that we can do this by submitting a POST request containing a reader to a link of type http://schema.yudu.com/readers. We check this operation is permitted by submitting an OPTIONS request to the URI provided in the readers link.

//Request
OPTIONS /Yudu/services/2.0/readers?timestamp=1412586005 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: 6XjiQUH2PTRDLXFtzRSGZQ20Fl7yOSOA2h2DA/V/jtw=

//Response
HTTP/1.1 204 No Content
Date: Mon, 06 Oct 2014 10:00:05 GMT
Allow: OPTIONS,POST,GET,HEAD

The Allow header tells us that the POST method is allowed for this resource so we submit a POST request containing a reader representation.

//Request
POST /Yudu/services/2.0/readers?timestamp=1412586010 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: YmYtVK8Se2GuFNlGNsRoiBT1WApfF85pPMVETI/FkFo=

<reader xmlns="http://schema.yudu.com">
  <username>example</username>
  <emailAddress>[email protected]</emailAddress>
  <firstName>Example</firstName>
  <lastName>User</lastName>
  <password>password</password>
  <nodeId>1234</nodeId>
</reader>

//Response
HTTP/1.1 201 CREATED
Date: Mon, 11 Jul 2011 10:00:10 GMT
Content-Type: application/vnd.yudu+xml
Location: https://api.yudu.com/Yudu/services/2.0/readers/5678

<reader xmlns="http://schema.yudu.com" id="5678">
  <username>example</username>
  <emailAddress>[email protected]</emailAddress>
  <firstName>Example</firstName>
  <lastName>User</lastName>
  <authorisedDeviceLimit>3</authorisedDeviceLimit>
  <nodeId>1234</nodeId>
  <links>
    <link rel="http://schema.yudu.com/reader" name="self"
          href="https://api.yudu.com/Yudu/services/2.0/readers/5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/permissions" name="permissions"
          href="https://api.yudu.com/Yudu/services/2.0/permissions?reader=5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/readerLogins" name="readerLogins"
          href="https://api.yudu.com/Yudu/services/2.0/readerLogins?reader=5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/subscriptions" name="subscriptions"
          href="https://api.yudu.com/Yudu/services/2.0/subscriptions?reader=5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/authorisedDevices" name="authorisedDevices"
          href="https://api.yudu.com/Yudu/services/2.0/readers/5678/authorisedDevices"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/authentication" name="authentication"
          href="https://api.yudu.com/Yudu/services/2.0/readers/5678/authentication"
          type="application/vnd.yudu+xml"/>
  </links>
</reader>

The response has returned the location of our new reader object in the Location header and the representation of the resource.

We wish to find all editions with a name starting with "Example". Make a GET request to the editions endpoint with the query parameter name=Example:

//Request
GET /Yudu/services/2.0/editions?name=Examp&timestamp=1412586015 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: k9PUkF0Vy9nQPnd5Dm6zRsXTyseOdlF+3F3/Bm0XUqY=

//Response
HTTP/1.1 200 OK
Date: Mon, 06 Oct 2014 10:00:15 GMT
Content-Type: application/vnd.yudu+xml

<editions xmlns="http://schema.yudu.com" limit="100" offset="0" total="2" truncated="false">
  <editionList>
    <edition id="5678">
      <name>Example 1</name>
      <publishedDate>2011-01-20T00:00:00Z</publishedDate>
      <links>
        <link rel="http://schema.yudu.com/edition" name="self"
              href="https://api.yudu.com/Yudu/services/2.0/editions/5678"
              type="application/vnd.yudu+xml"/>
        <link rel="http://schema.yudu.com/permissions" name="permissions"
              href="https://api.yudu.com/Yudu/services/2.0/permissions?edition=5678"
              type="application/vnd.yudu+xml"/>
        <link rel="http://schema.yudu.com/subscriptions" name="subscriptions"
              href="https://api.yudu.com/Yudu/services/2.0/subscriptions?edition=5678"
              type="application/vnd.yudu+xml"/>
      </links>
    </edition>
    <edition id="9012">
      <name>Example 2</name>
      <publishedDate>2011-01-27T12:24:00Z</publishedDate>
      <links>
        <link rel="http://schema.yudu.com/edition" name="self"
              href="https://api.yudu.com/Yudu/services/2.0/editions/9012"
              type="application/vnd.yudu+xml"/>
        <link rel="http://schema.yudu.com/permissions" name="permissions"
              href="https://api.yudu.com/Yudu/services/2.0/permissions?edition=9012"
              type="application/vnd.yudu+xml"/>
        <link rel="http://schema.yudu.com/subscriptions" name="subscriptions"
              href="https://api.yudu.com/Yudu/services/2.0/subscriptions?edition=9012"
              type="application/vnd.yudu+xml"/>
      </links>
    </edition>
  </editionList>
  <links/>
</editions>

The response body contains an edition list representation. Note that since the resulting list has not been truncated the editions element contains an empty links element as there are no further pages of results to navigate.

Given the above examples, we can now create a permission for this reader and one of the editions we found:

//Request
POST /Yudu/services/2.0/permissions?timestamp=1412586020 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: Xmvv80WIub0NazhL8TV50h4wxWxHuUs9cVYeASnoTFE=

<permission xmlns="http://schema.yudu.com">
  <reader id="5678"/>
  <edition id="9012"/>
</permission>

//Response
HTTP/1.1 201 CREATED
Date: Mon, 06 Oct 2014 10:00:20 GMT
Content-Type: application/vnd.yudu+xml
Location: https://api.yudu.com/Yudu/services/2.0/permissions/3456

<permission id="3456">
  <reader id="5678"/>
  <edition id="9012"/>
  <creationDate>2014-10-06T10:00:20Z</creationDate>
  <links>
    <link rel="http://schema.yudu.com/permission" name="self"
          href="https://api.yudu.com/Yudu/services/2.0/permissions/3456"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/reader" name="reader"
          href="https://api.yudu.com/Yudu/services/2.0/readers/5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/edition" name="edition"
          href="https://api.yudu.com/Yudu/services/2.0/editions/9012"
          type="application/vnd.yudu+xml"/>
  </links>
</permission>

Now we update the permission and add an expiry date:

//Request
PUT /Yudu/services/2.0/permissions/3456?timestamp=1412586025 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: 4fUApJWR72cBwYfB00AtcJht5OhwhpuW9QCNq9jFePY=

<permission xmlns="http://schema.yudu.com" id="3456">
  <expiryDate>2015-06-01T00:00:00Z</expiryDate>
</permission>

//Response
HTTP/1.1 200 OK
Date: Mon, 06 Oct 2014 10:00:25 GMT
Content-Type: application/vnd.yudu+xml

<permission id="3456">
  <reader id="5678"/>
  <edition id="9012"/>
  <creationDate>2014-10-06T10:00:20Z</creationDate>
  <expiryDate>2015-06-01T00:00:00Z</expiryDate>
  <links>
    <link rel="http://schema.yudu.com/permission" name="self"
          href="https://api.yudu.com/Yudu/services/2.0/permissions/3456"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/reader" name="reader"
          href="https://api.yudu.com/Yudu/services/2.0/readers/5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/edition" name="edition"
          href="https://api.yudu.com/Yudu/services/2.0/editions/9012"
          type="application/vnd.yudu+xml"/>
  </links>
</permission>

Suppose we need to change a reader's password:

//Request
PUT /Yudu/services/2.0/readers/5678?timestamp=1412586030 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: VN7B4U5Uv4X4Yx+2qt7WUzCLBbb7Ssejaf1XHOmtACI=

<reader xmlns="http://schema.yudu.com" id="5678">
  <password>newPassword</password>
</reader>

//Response
HTTP/1.1 200 OK
Date: Mon, 06 Oct 2014 10:00:30 GMT
Content-Type: application/vnd.yudu+xml

<reader xmlns="http://schema.yudu.com" id="5678">
  <username>example</username>
  <emailAddress>[email protected]</emailAddress>
  <firstName>Example</firstName>
  <lastName>User</lastName>
  <authorisedDeviceLimit>3</authorisedDeviceLimit>
  <nodeId>1234</nodeId>
  <links>
    <link rel="http://schema.yudu.com/reader" name="self"
          href="https://api.yudu.com/Yudu/services/2.0/readers/5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/permissions" name="permissions"
          href="https://api.yudu.com/Yudu/services/2.0/permissions?reader=5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/readerLogins" name="readerLogins"
          href="https://api.yudu.com/Yudu/services/2.0/readerLogins?reader=5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/subscriptions" name="subscriptions"
          href="https://api.yudu.com/Yudu/services/2.0/subscriptions?reader=5678"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/authorisedDevices" name="authorisedDevices"
          href="https://api.yudu.com/Yudu/services/2.0/readers/5678/authorisedDevices"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/authentication" name="authentication"
          href="https://api.yudu.com/Yudu/services/2.0/readers/5678/authentication"
          type="application/vnd.yudu+xml"/>
  </links>
</reader>

Suppose we wish to find all iDevice enabled publications. Suppose further that we wish to see 2 publications at a time and navigate through the whole list:

//Request
GET /Yudu/services/2.0/publications/?iDeviceEnabled=true&limit=2&timestamp=1412586035 HTTP/1.1
Host: api.yudu.com
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: qXRVLXasp6li50Z2WAsn9WSiWeDWz54seyFdisRYbew=

//Response
HTTP/1.1 200 OK
Date: Mon, 06 Oct 2014 10:00:35 GMT
Content-Type: application/vnd.yudu+xml

<publications xmlns="http://schema.yudu.com" limit="2" offset="0" total="3" truncated="true">
  <publicationList>
    <publication id="2345">
      <name>Publication 1</name>
      <iDeviceEnabled>true</iDeviceEnabled>
      <androidEnabled>false</androidEnabled>
      <links>
        <link rel="self" name="self"
              href="https://api.yudu.com/Yudu/services/2.0/publications/2345"
              type="application/vnd.yudu+xml"/>
      </links>
    </publication>
    <publication id="6789">
      <name>Publication 2</name>
      <iDeviceEnabled>true</iDeviceEnabled>
      <androidEnabled>true</androidEnabled>
      <links>
        <link rel="self" name="self"
              href="https://api.yudu.com/Yudu/services/2.0/publications/6789"
              type="application/vnd.yudu+xml"/>
      </links>
    </publication>
  <publicationList>
  <links>
    <link rel="http://schema.yudu.com/publications" name="next"
          href="http://api.yudu.com/Yudu/services/2.0/publications?limit=2&amp;offset=2"
          type="application/vnd.yudu+xml"/>
  </links>
</publications>

We can see that there were 3 results and we are only seeing the first two, as per our limit parameter. Now we can see the next result by following the next link, which adds an offset=2 parameter.

//Request
GET /Yudu/services/2.0/publications/?iDeviceEnabled=true&limit=2&offset=2&timestamp=1412586040 HTTP/1.1
Host: api.yudu.com
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: 5P4EF0iS/trLXUWZ0e6U+WSbfX3oBAy0YirfWOwx6KM=

//Response
HTTP/1.1 200 OK
Date: Mon, 06 Oct 2014 10:00:40 GMT
Content-Type: application/vnd.yudu+xml

<publications xmlns="http://schema.yudu.com" limit="2" offset="2" total="3" truncated="true">
  <publicationList>
    <publicationid="4321">
      <name>Publication 3</name>
      <iDeviceEnabled>true</iDeviceEnabled>
      <androidEnabled>false</androidEnabled>
      <links>
        <link rel="self" name="self"
              href="https://api.yudu.com/Yudu/services/2.0/publications/4321"
              type="application/vnd.yudu+xml"/>
      </links>
    </publication>
  <publicationList>
  <links>
    <link rel="http://schema.yudu.com/publications" name="previous"
          href="http://api.yudu.com/Yudu/services/2.0/publications?limit=2&amp;offset=0"
          type="application/vnd.yudu+xml"/>
  </links>
</publications>

Now the service returns the final publication and the only link available is the previous link to take us back to an offset of 0.

Suppose we wish to find all subscriptions which contain the edition with id 5678. Furthermore, suppose we wish to order the results by subscriptionType, in descending order:

//Request
GET /Yudu/services/2.0/subscriptions/?edition=5678&sort=subscriptionType_desc&timestamp=1412586045 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: ipNslQR4oH6lWhx9Kqr5pNKs7T8zg6TNzgifWnQtl8M=

//Response
HTTP/1.1 200 OK
Date: Mon, 06 Oct 2014 10:00:45 GMT
Content-Type: application/vnd.yudu+xml

<subscriptions xmlns="http://schema.yudu.com" limit="100" offset="0" count="2" truncated="false">
  <subscriptionList>
    <subscription id="9876">
      <title>Universal Subscription</title>
      <onDeviceTitle>subscription on device</onDeviceTitle>
      <subscriptionType>universal_club</subscriptionType>
      <disabled>false</disabled>
      <defaultAuthorisedDeviceLimit>6</defaultAuthorisedDeviceLimit>
      <nodeId>1234</nodeId>
      <links>
        <link rel="http://schema.yudu.com/subscription" name="self"
              href="https://api.yudu.com/Yudu/services/2.0/subscriptions/9876"
              type="application/vnd.yudu+xml"/>
        <link rel="http://schema.yudu.com/readers" name="readers"
              href="https://api.yudu.com/Yudu/services/2.0/readers?subscription=9876"
              type="application/vnd.yudu+xml"/>
        <link rel="http://schema.yudu.com/editions" name="editions"
              href="https://api.yudu.com/Yudu/services/2.0/editions?subscription=9876"
              type="application/vnd.yudu+xml"/>
      </links>
    </subscription>
    <subscription id="5432">
      <title>Example Subscription</title>
      <onDeviceTitle>A Subscription</onDeviceTitle>
      <subscriptionType>flash_node</subscriptionType>
      <disabled>true</disabled>
      <defaultAuthorisedDeviceLimit>3</defaultAuthorisedDeviceLimit>
      <nodeId>1234</nodeId>
      <links>
        <link rel="http://schema.yudu.com/subscription" name="self"
              href="https://api.yudu.com/Yudu/services/2.0/subscriptions/5432"
              type="application/vnd.yudu+xml"/>
        <link rel="http://schema.yudu.com/readers" name="readers"
              href="https://api.yudu.com/Yudu/services/2.0/readers?subscription=5432"
              type="application/vnd.yudu+xml"/>
        <link rel="http://schema.yudu.com/editions" name="editions"
              href="https://api.yudu.com/Yudu/services/2.0/editions?subscription=5432"
              type="application/vnd.yudu+xml"/>
      </links>
    </subscription>
  </subscriptionList>
  <links/>
</subscriptions>

Given the above examples, we can now create a subscription period for a reader and subscription:

//Request
POST /Yudu/services/2.0/subscriptionPeriods/?timestamp=1412586050 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: azckQ5GtqtDQe0EW6v5EBsC79QMXg9e/k1yezUKPFjA=

<subscriptionPeriod xmlns="http://schema.yudu.com">
  <reader id="1234"/>
  <subscription id="9876"/>
  <startDate>2014-11-01T00:00:00Z</startDate>
  <expiryDate>2016-11-01T00:00:00Z</expiryDate>
</subscriptionPeriod>

//Response
HTTP/1.1 201 CREATED
Date: Mon, 06 Oct 2014 10:00:50 GMT
Content-Type: application/vnd.yudu+xml
Location: https://api.yudu.com/Yudu/services/2.0/subscriptionPeriods/7654

<subscriptionPeriod xmlns="http://schema.yudu.com" id="7654">
  <reader id="1234"/>
  <subscription id="9876"/>
  <startDate>2014-11-01T00:00:00Z</startDate>
  <expiryDate>2016-11-01T00:00:00Z</expiryDate>
  <links>
    <link rel="http://schema.yudu.com/subscriptionPeriod" name="self"
          href="https://api.yudu.com/Yudu/services/2.0/subscriptionPeriods/7654"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/reader" name="reader"
          href="https://api.yudu.com/Yudu/services/2.0/readers/1234"
          type="application/vnd.yudu+xml"/>
    <link rel="http://schema.yudu.com/subscription" name="subscription"
          href="https://api.yudu.com/Yudu/services/2.0/subscriptions/9876"
          type="application/vnd.yudu+xml"/>
  </links>
</subscriptionPeriod>

Suppose a reader has logged in from too many different devices and you would like to reset their authorised devices so that they can log in from a new collection of devices. This is achieved by deleting all authorised devices associated with the reader:

//Request
DELETE /Yudu/services/2.0/readers/1234/authorisedComputers/?timestamp=1412586055 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: bGCNgoiseJ7qom8R1czUxoBlmMTSkpRgeccVOQO+VoY=

//Response
HTTP/1.1 204 NO CONTENT
Date: Mon, 06 Oct 2014 10:00:55 GMT

Given a the username and password for a reader we can check whether such a reader exists and whether the password submitted by the reader is correct. First find a reader.

//Request
GET /Yudu/services/2.0/readers/?username=example&timestamp=1412586060 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: h/jKtsHKkNvAb87mElz5xFr9y7/9XaZGcD8qDwjgiFo=

//Response
HTTP/1.1 200 OK
Date: Mon, 11 Jul 2011 10:01:00 GMT
Content-Type: application/vnd.yudu+xml

<readers xmlns="http://schema.yudu.com" limit="100" offset="0" count="1" truncated="false">
  <reader id="5678">
    <username>example</username>
    <emailAddress>[email protected]</emailAddress>
    <firstName>Example</firstName>
    <lastName>User</lastName>
    <authorisedDeviceLimit>3</authorisedDeviceLimit>
    <nodeId>1234</nodeId>
    <links>
      <link rel="http://schema.yudu.com/reader" name="self"
            href="https://api.yudu.com/Yudu/services/2.0/readers/5678"
            type="application/vnd.yudu+xml"/>
      <link rel="http://schema.yudu.com/permissions" name="permissions"
            href="https://api.yudu.com/Yudu/services/2.0/permissions?reader=5678"
            type="application/vnd.yudu+xml"/>
      <link rel="http://schema.yudu.com/readerLogins" name="readerLogins"
            href="https://api.yudu.com/Yudu/services/2.0/readerLogins?reader=5678"
            type="application/vnd.yudu+xml"/>
      <link rel="http://schema.yudu.com/subscriptions" name="subscriptions"
            href="https://api.yudu.com/Yudu/services/2.0/subscriptions?reader=5678"
            type="application/vnd.yudu+xml"/>
      <link rel="http://schema.yudu.com/authorisedDevices" name="authorisedDevices"
            href="https://api.yudu.com/Yudu/services/2.0/readers/5678/authorisedDevices"
            type="application/vnd.yudu+xml"/>
      <link rel="http://schema.yudu.com/authentication" name="authentication"
            href="https://api.yudu.com/Yudu/services/2.0/readers/5678/authentication"
            type="application/vnd.yudu+xml"/>
    </links>
  </reader>
</readers>

Then follow the authentication link for the reader and make a PUT with an authentication representation:

//Request
PUT /Yudu/services/2.0/readers/?username=aUsername&timestamp=1412586065 HTTP/1.1
Accept: application/vnd.yudu+xml
Authentication: abcd1234
Signature: ujp8wI5gGPwIBON3lzQD/ZY5qtR3zLBd/zKc4aNF5/c=

<authentication xmlns="http://schema.yudu.com">
  <password>userPassword</password>
</authentication>

//Response
HTTP/1.1 200 OK
Date: Mon, 11 Jul 2011 10:01:05 GMT
Content-Type: application/vnd.yudu+xml

<authentication xmlns="http://schema.yudu.com">
  <authenticated>false</authenticated>
</authentication>

The reader's password is not correct.