Yindo API Help Page

Introduction

To use the Yindo API you will need a VendorKey. Contact us to obtain one. The VendorKey should be supplied to the API in a X-VendorKey header:

X-VendorKey: 11111111-2222-3333-4444-555555555555

To access specific versions of this API you will need to supply the version parameter in the accept header:

Accept: application/json; version=2

The current version is 2, the default version is 2

Loggin in

Certain methods require a user th be logged in. To do so you can use the /Token endpoint. When the user is sucessfully logged in, both a Bearer token and a SessionKey will be returned. Both need to be supplied through headers. The Bearer token should be supplied to the API in the Authorization header:

Authorization: Bearer <token>

The SessionKey should be supplied to the API in the X-SessionKey header:

X-SessionKey: 11111111-2222-3333-4444-555555555555

The session expires after a set period of inactivity and can be manually renewed by making a PUT request to the /api/usersession method. Registering reading statistics (/api/usersession/book/{ean} and /api/usersession/book/{ean}/page/{page}) will also renew the session.

Parents and Children

Once logged in, the userID for a parent will be encoded in the Bearer token. The userID doesn not need to be supplied separately. The childID for an actively selected child (either use the element children in the main profile , or explicitly request a list of children) should be supplied to the API in the X-ChildID header:

X-ChildID: 11111111-2222-3333-4444-555555555555

Methods that register statistics, preferences or behaviour usually require both a logged in user with a valid session, and a selected childID. If a childID is not supplied, the method operates on the userID.

Account

The Account API provides a means for the user to log out and update his of her password.
NEw accounts cannot be created through this public facing API. To create a new account, the vendor API must be used.
This API requires an authorized user

API	Description
GET api/account/userinfo	V2 - This method retrieves information about the currently logged in user
POST api/account/logout	V2 - This method logs the currently logged in user out of the system
POST api/account/revalidate	V2 - This method revalidates the users username and password
POST api/account/changepassword	V2 - This method allows the currently logged in user to change his or her password

Book

The Book API operates on single books, allowing you to retrieve the specifics for a single book.

API	Description
GET api/book/{ean}	V2 - This method retrieves the details for a given book.
GET api/book/{ean}/page/{page}/{size}	V2 - This method retrieves a specific page in base64 PNG format for for the given book.
GET api/book/{ean}/pagepng/{page}/{size}/{token}	V2 - This method retrieves a specific page in PNG format for for the given book.
GET api/book/{ean}/frontcover/{size}	V2 - This method retrieves the backcover for the given book in PNG format
GET api/book/{ean}/backcover/{size}	V2 - This method retrieves the backcover for the given book in PNG format
GET api/book/details/{ean}/{userid}	V1 - Retourneert de details van een boek in het formaat YindoBook

Books

The Books API operates on collections of books, such as new or popular books.

API	Description
GET api/books/all	V2 - Retrieves a list of all available books for the current vendor
GET api/books/updated/{date}	V2 - Retrieves a list of new or updated (since the supplied date) books for the current vendor.
GET api/books/{ageLevel}/{count}	V2 - Retrieves a list of books.
GET api/books/popular/{ageLevel}/{count}	V2 - Retrieves a list of popular books.
GET api/books/new/{ageLevel}/{count}	V2 - Retrieves a list of new books.
GET api/books/{ageLevel}/{page}/{size}	V2 - Retrieves a paged list of books.
GET api/books/filtered/{ageLevel}/{category}/{avilevel}	V2 - Retrieves a list of books, filtered by the supplied values. This list will be randomized.
GET api/books/filtered/{ageLevel}/{category}/{avilevel}/{count}	V2 - Retrieves a list of books, filtered by the supplied values. This list will be randomized and limited to the specified amount of elements.
GET api/books/recommended/{count}	V2 - Retrieves a randomized list of recommended books for the logged in child, depending on which is available. This list will be randomized. This method requires an authorized user.
GET api/books/read/{count}	V2 - Retrieves a list of books read by the user or the logged in child, depending on which is available. This list will be orderd by read date, in descending order. This method requires an authorized user.
GET api/books/read/{childID}/{count}	V2 - Retrieves a list of books read by the user or the logged in child, depending on which is available. This list will be orderd by read date, in descending order. This method requires an authorized user.
GET api/books/search/{keywords}	V2 - This method searches all content of all available books for the supplied keywords.
GET api/books/search/keywords/{keywords}	V2 - This method searches the keywords of all available books for the supplied keywords.
GET api/books/search/titles/{keywords}	V2 - This method searches the titles of all available books for the supplied keywords.
GET api/books/search/authors/{keywords}	V2 - This method searches the authors for all available books for the supplied keywords.
GET api/books/all/{page}/{size}	V1 - Retourneert alle boeken als paged result set.
GET api/books/update/{date}	V1 - Retourneert alle boeken sinds een bepaalde dataum
GET api/books/default/{count}	V1 - Retourneert de standaard boeken.
GET api/books/related/{ean}/{count}	V1 - Retourneert alle boeken die gerelateerd zijn aan de opgegeven titel.

Favorite

The Favorites API operates on a favorites for the currently active Child or the currently logged in user, allowing you to add, remove or retrieve favorites This API requires an authorized user, and a child-id supplied through the custom header X-ChildID.
If no ChildID is supplied, these methods will operate on the currently active user.

API	Description
POST api/favorite/book/{ean}	V2 - This method adds a favorite book for the currently logged in user or child
DELETE api/favorite/book/{ean}	V2 - This method removes a favorite for the currently logged in user
GET api/favorite/books	V2 - This method retrieves all favorites for the currently logged in user
GET api/favorite/books/{userid}	V2 - This method retrieves all favorite books for the currently selected user/child. NOTE: this method ignores the X-ChildID header.
POST api/favorite/category/{id}	V2 - This method adds a favorite category for the currently logged in user or child. The available categories can be retrieved through the /api/filters/categories method.
POST api/favorite/category/{id}/{userid}	V2 - This method adds a favorite category for the specified user or child. The available categories can be retrieved through the /api/filters/categories method. NOTE: this method ignores the X-ChildID header.
DELETE api/favorite/category/{id}	V2 - This method removes a favorite category for the currently logged in user or child
DELETE api/favorite/category/{id}/{userid}	V2 - This method removes a favorite category for the specified user or child. NOTE: this method ignores the X-ChildID header.
GET api/favorite/categories	V2 - This method retrieves all favorite categories for the currently logged in user or selected child.
GET api/favorite/categories/{userid}	V2 - This method retrieves all favorite categories for the selected user/child. NOTE: this method ignores the X-ChildID header.

Filters

The Filters API retrieves lists of filters.

API	Description
GET api/filters/agelevels	V2 - This method retrieves the available agegroups for the specified vendorkey.
GET api/filters/categories	V2 - This method retrieves the available categories for the specified vendorkey.
GET api/filters/avilevels	V2 - This method retrieves the available avilevels.

Order

The /Order endpoint is used to log a user into the system.

API	Description
GET api/order/buyingoptions	No documentation available.
POST api/order/arrangement	No documentation available.

Profile

The Profile API operates on the profile for a single user, allowing you to create a user or retrieve and modify user details This API requires an authorized user

API	Description
GET api/profile	V2 - Gets the userprofile for the currently logged in user.
GET api/profile/main	V2 - Gets the main (parent) profile for the currently logged in user.
GET api/profile/child/{childID}	V2 - Gets a child profile.
GET api/profile/children	V2 - Gets the userprofile for the currently logged in user.

Rating

API	Description
POST api/rating/book/{ean}/{rating}	V2 - This method registers the rating for the specified book for the currently logged in user or child.
DELETE api/rating/book/{ean}	V2 - This method removes the rating for the specified book for the currently logged in user or child.
GET api/rating/books	V2 - This method retrieves all books with a rating for the currently logged in user or child.
GET api/rating/book/{ean}	V2 - This method retrieves the rating for the specified book for the currently logged in user or child.

Subscription

The Subscription API operates on subscriptions for the currently logged in user, allowing you to add, remove or retrieve subscriptions.
This API requires an authorized user.

API	Description
POST api/subscription/{subscriptionID}	V2 - Adds a subscription to the currently logged in user
DELETE api/subscription/{subscriptionID}	V2 - Removes a subscription from the currently logged in user
GET api/subscriptions	V2 - Returns all active subscriptions for the currently logged in user
GET api/subscriptions/available	V2 - Returns all available subscriptions
GET api/subscription/{id}/books	V2 - Retrieves all books for a given subscription

Token

The /Token endpoint is used to log a user into the system.

API	Description
POST token	V2 - The /token endpoint is used to log a user into the system. Contrary to most methods in this API, this method does not expect JSON in the request body. Instead it expects the parameters in application/x-www-form-urlencoded format: grant_type=password&username=theuser&password=thepass
GET api/token/create/{code}/{book}	Creates a reading token.
GET api/{vkey}/token/create/{email}/{book}	Creates a reading token.

API

Description

POST token

V2 - The /token endpoint is used to log a user into the system.
Contrary to most methods in this API, this method does not expect JSON in the request body.
Instead it expects the parameters in application/x-www-form-urlencoded format:

            grant_type=password&username=theuser&password=thepass

GET api/token/create/{code}/{book}

Creates a reading token.

GET api/{vkey}/token/create/{email}/{book}

Creates a reading token.

UserSession

The Session(s) API operates on sessions for a single user, allowing you to create a user or retrieve and modify user details This API requires an authorized user

API	Description
GET api/usersession	V2 - Gets a new active session for the currently logged in user. If the maximum number of sessions for this user has been reached, an empty invalid session is returned. It is usually not nessecary to manually request a new active session as one is created upon login.
GET api/usersession/{clientKey}	V2 - Gets a new or active session for the currently logged in user. The session will be linked to the supplied clientKey. If the maximum number of sessions for this user with this key has been reached, an empty invalid session is returned. It is usually not nessecary to manually request a new active session as one is created upon login.
GET api/usersession/{key}	V2 - Gets a the details for a specific session.
PUT api/usersession	V2 - Touches the active session for the currently logged in user, therefore prolonging its lifetime. The sessionkey is supplied through the custom header X-SessionKey.
DELETE api/usersession	V2 - Ends the active session for the currently logged in user. Alternatively the session can be ended by loggin the user out. The sessionkey is supplied through the custom header X-SessionKey.
GET api/usersessions	V2 - Gets all active sessions for the currently logged in user.
POST api/usersession/book/{ean}	V2 - Registers the specified book as being read or opened.
POST api/usersession/book/{ean}/page/{page}	V2 - Registers the specified book as being read or opened.