Zoom/Embed

Overview

The PRH API implements the Zoom/Embed pattern to make it possible to include data from multiple resources in the same request. By specifying a resource type in the "zoom" parameter, the related objects of that type are included in the "_embeds" array in the response.

Specifying the "zoom" param

Each resource is identified by a "rel" value. For example the "rel" for the Title resource is:

https://api.penguinrandomhouse.com/title/titles/definition

You can find these "rel" values by inspecting the "_links" array in any response. The list of links on an object tell you which types of objects are candidates to be embedded in the response.

Once you have found the "rel" to identify the resource you want, simply use that value as the "zoom" parameter.

An example

Let's start by getting back data for a specific ISBN:

/domains/PRH.US/titles/9780307269768

We can inspect the response and see the "_links" object that will list that title's authors:

          {
            "rel": "https:\/\/api.penguinrandomhouse.com\/title\/authors\/definition",
            "href": "https:\/\/api.penguinrandomhouse.com\/title\/domains\/PRH.US\/titles\/9780307269768\/authors",
            "method": "GET",
            "parameters": null
          },

Now take that "rel" value and specify that as our "zoom" parameter:

/domains/PRH.US/titles/9780307269768?zoom=https://api.penguinrandomhouse.com/title/authors/definition 

The response contains an "_embeds" array with an "authors" element in it:

    "_embeds": [
      {
        "authors": [
          {
            "authorId": 21567,
            "display": "Alice Munro",
            "first": "Alice",
            "last": "Munro",
            "seoFriendlyUrl": "\/authors\/21567\/alice-munro",
            "contribRoleCode": "A",
            "contribRoleDesc": "Author",
            "_embeds": null,
            "_links": [
              ...
            ]
          }
        ],
        "_embeds": null,
        "_links": [
          
        ]
      }