Subject Resource

Introduction

The Subject resource provides a framework for managing subject categories within a publishing platform. This resource supports multi-language fields, enabling subject names and descriptions to be localized for various languages. It also includes links to related resources and identifiers for integration with external classification systems.

Subject Object

The subject resource includes the following fields:

Field	Type	Description	Possible Values	Default
`_id`	Integer	Unique identifier for the subject.
`_links`	Object	Links to related resources.	See structured fields
`bisac`	Array	BISAC codes associated with the subject.	Valid BISAC codes
`description`	String	A brief description of the subject.	Any string	Empty
`identifier`	String	External identifier for the subject.	Any string	Null
`labels`	Array	List of labels categorizing the subject.	Array of strings	Empty
`name`	Array	Multi-language representation of the subject (s. Multi-language Representation Format).	Array of name objects	Empty
`realm`	Object	Reference to the realm to which the subject belongs.	Realm object
`vlb`	Array	VLB (German book trade) subject codes.	Array of valid VLB codes

Managing Subject Resources

GET: Retrieving a Subject

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

Endpoint

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

Response Structure

The response is a JSON object with the Subject Object.

POST: Creating a New Subject

New subject 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/subjects

Request Body Example

{
  "bisac": ["SOC026000"],
  "description": "A category related to social sciences.",
  "identifier": "12345",
  "labels": ["Society"],
  "name": [
    { "language": "eng", "text": "Sociology" },
    { "language": "ger", "text": "Soziologie" }
  ],
  "realm": { "_id": 1 },
  "vlb": ["720"]
}

PUT: Updating an Existing Subject

Existing subject 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/subjects/[ID]

Request Body Example

{
  "description": "Updated description of the subject.",
  "labels": ["Society", "Culture"]
}

DELETE: Deleting a Subject

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

Endpoint

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

Resource Queries

Querying Subjects (GET)

Endpoint

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

This endpoint supports filters and pagination for querying subject data.

Response Structure

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

Each item in the items array represents a single subject.

Query Parameters

Parameter	Description	Notes
`name`	Filter by subject name.	Supports equal-operator (exact match) only
`identifier`	Filter categories by identifier.	Supports equal-operator (exact match) only
`q`	Perform a full-text search across multiple fields.

Examples

Example 1: Querying Subjects with Filters

GET https://api.openpublishing.com/resource/v3/subjects?name=Sociology

Example 2: Querying Subjects by BISAC Code

GET https://api.openpublishing.com/resource/v3/subjects?q=SOC026000