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
• 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.
• 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.

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 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>user@example.com</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>
  <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>user@example.com</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.

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 ?emailAddress=user@example.com&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/1.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/1.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>user@example.com</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/1.0/readers/5678

<reader xmlns="http://schema.yudu.com" id="5678">
  <username>example</username>
  <emailAddress>user@example.com</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/1.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/1.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/1.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/1.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/1.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>user@example.com</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/1.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/1.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/1.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/1.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/1.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/1.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/1.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/1.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/1.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/1.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>user@example.com</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/1.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.