Skip to content

Set Resource

Introduction

The Set resource provides a way to group and manage collections of related items, such as books, articles, or other assets. This resource supports linked resources and includes features like identifiers and metadata for organization and retrieval. While sets often include books from a series, they can also include unrelated books that are grouped for thematic or practical reasons. A set is more about the packaging and marketing, rather than the narrative connection.

Set Object

The Set resource includes the following fields:

Field Type Description Possible values Default
_id Integer The unique identifier of the set.
_links Object Links to related resources, such as self or metrics (s. set metrics).
description String A detailed description of the set. null
href String URL to access the set in the storefront (read only value). null
identifier String A unique identifier for the set.
name String (required) The display name of the set.
realm Object Information about the realm associated with the set, including its ID, name, and links.

Managing Set Resources

GET: Retrieving a Set

A Set can be fetched by its unique ID using an HTTP GET request.

Endpoint

GET https://api.openpublishing.com/resource/v3/sets/[ID]

Response Structure

The response is a JSON object with the Set object.

POST: Creating a New Set

New Set resources can be added using an HTTP POST request. The request must include all required fields for the resource in the body.

Endpoint

POST https://api.openpublishing.com/resource/v3/sets

Request Body Example

{
    "description": "A collection of science fiction novels by popular authors.",
    "href": "https://www.goldenpage.com/sets/42",
    "identifier": "SCI_FI_COLLECTION",
    "name": "Science Fiction Collection",
    "realm": {
        "_id": 334,
        "_links": {
            "self": "https://api.openpublishing.com/resource/v3/realms/334"
        },
        "name": "goldenpage",
        "screenname": "Golden Page Press"
    }
}

PUT: Updating an Existing Set

Existing Set resources can be updated using an HTTP PUT request. The request body should contain the updated fields.

Endpoint

PUT https://api.openpublishing.com/resource/v3/sets/[ID]

Request Body Example

{
  "description": "A collection of science fiction novels by modern authors.",
  "name": "Modern Science Fiction Collection"
}

DELETE: Deleting a Set

Set resources can be deleted using an HTTP DELETE request. This action permanently removes the resource.

Endpoint

DELETE https://api.openpublishing.com/resource/v3/sets/[ID]

Resource Queries

Querying Sets (GET)

Endpoint

GET https://api.openpublishing.com/resource/v3/sets

This endpoint supports filters and pagination for querying Set data.

Response Structure

Field Type Description
_links Object Links to related resources
items Array An array of individual Set objects

Each item in the items array represents a single Set.

Query Parameters

Parameter Description Notes
identifier Filter sets by identifier Exact matching
name Filter sets by name Exact matching
q Fulltext search

Examples

Example 1: Querying Sets with Filters

GET https://api.openpublishing.com/resource/v3/sets?identifier=SCI_FI_COLLECTION

Example 2: Querying Sets by Fulltext

GET https://api.openpublishing.com/resource/v3/sets?q=science%20fiction

Example JSON Responses

Example 1

{
    "_id": 201,
    "_links": {
        "metrics": "https://api.openpublishing.com/resource/v3/sets/201/metrics",
        "self": "https://api.openpublishing.com/resource/v3/sets/201"
    },
    "description": "A collection of timeless children's books like Alice's Adventures in Wonderland by Lewis Carroll, Peter Pan by J.M. Barrie, and The Secret Garden by Frances Hodgson Burnett.",
    "href": "https://www.goldenpage.com/sets/201",
    "identifier": "CHILDREN_LITERATURE",
    "name": "Classic Children's Literature Set",
    "realm": {
        "_id": 334,
        "_links": {
            "self": "https://api.openpublishing.com/resource/v3/realms/334"
        },
        "name": "goldenpage",
        "screenname": "Golden Page Press"
    }
}

Example 2

{
    "_id": 207,
    "_links": {
        "metrics": "https://api.openpublishing.com/resource/v3/sets/207/metrics",
        "self": "https://api.openpublishing.com/resource/v3/sets/207"
    },
    "description": "A curated set of books by Agatha Christie, focusing on her most popular detective stories.",
    "href": "https://www.goldenpage.com/sets/207",
    "identifier": "AGATHA_CHRISTIE_MYSTERY",
    "name": "Agatha Christie Mystery Collection",
    "realm": {
        "_id": 334,
        "_links": {
            "self": "https://api.openpublishing.com/resource/v3/realms/334"
        },
        "name": "goldenpage",
        "screenname": "Golden Page Press"
    }
}