Category Resource

Introduction

The Category resource provides a structured way to categorize items such as products, or other entities. This resource supports multi-language fields and links to related resources for enhanced contextual understanding.

Category Object

The category resource includes the following fields:

Field	Type	Description	Possible values	Default
_id	Integer	Unique identifier for the category.	Positive integers	None
_links	Object	Links to related resources.	URLs	None
identifier	String	Unique category identifier (optional).	Alphanumeric string	None
name	Array	Multi-language names of the category. (s. Multi-language Representation Format)	Array of name objects	None
realm	Object	Reference to the realm to which the category belongs.	Realm object	None

Managing Category Resources

GET: Retrieving a Category

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

Endpoint

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

Response Structure

The response is a JSON object with the Category Object.

POST: Creating a New Category

New category 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/categories

Request Body Example

{
   "identifier": "bachelor_thesis",
   "name": [
      {
         "language": "eng",
         "name": "Bachelor Thesis"
      },
      {
         "language": "ger",
         "name": "Bachelorarbeit"
      }
   ]
}

PUT: Updating an Existing Category

Existing category 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/categories/[ID]

Request Body Example

{
   "name": [
      {
         "language": "eng",
         "name": "Diploma thesis"
      },
      {
         "language": "ger",
         "name": "Diplomarbeit"
      }
   ]
}

DELETE: Deleting a Category

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

Endpoint

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

Resource Queries

Querying Categories (GET)

Endpoint

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

This endpoint supports filters and pagination for querying category data. Please refer to resource queries syntax to filter and refine your search results.

Response Structure

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

Each item in the items array represents a single category.

Query Parameters

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

Examples

Example 1: Querying Categories with Filters

GET https://api.openpublishing.com/resource/v3/categories?q=thesis

Example 2: Querying Categories by Name

GET https://api.openpublishing.com/resource/v3/categories?name=Thesis
GET https://api.openpublishing.com/resource/v3/categories?name__contains=thesis

Example 3: Querying Categories by Identifier

GET https://api.openpublishing.com/resource/v3/categories?identifier=VBCOL