The Third Iron Public API++ lets developers retrieve and traverse a library’s BrowZine taxonomy using simple RESTful GET requests. This guide covers the basics and implementation patterns for working with subjects, bookcases, bookshelves, and journals.

Overview

In short, the interaction between your application and the taxonomy endpoints is a RESTful interaction using GET requests against a library-specific API path.

You provide:

• Library ID - identifies the library whose BrowZine taxonomy you want to browse

• API Key - the access token associated with that library

• A starting path - usually the root subjects endpoint

In return, you get JSON responses that let you move through the taxonomy tree:

• Subjects - the top-level areas shown on a library’s BrowZine homepage

• Bookcases - subdivisions within a subject when applicable

• Bookshelves - the taxonomy level directly above journals

• Journals - title lists available from a subject, bookcase, or bookshelf context

• Parent pointers - links that help your client move back up the tree without having to infer relationships

The User Experience

This endpoint is designed for developers building browsable journal experiences on library websites, discovery layers, or internal tools. A common pattern is:

Load Subjects → Let the user choose a subject → Show bookcases or bookshelves → Show journals

Because responses include parent relationships, your interface can support both downward navigation and “back up” navigation without custom taxonomy logic. That is especially useful when journals can be requested from multiple levels in the hierarchy.

Endpoint Patterns

Use your Library ID and API key with paths like the following:

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/subjects?access_token={API_KEY}

From there, clients should follow returned links to traverse the tree. Common patterns include:

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/subjects/{SUBJECT_ID}/bookcases?access_token={API_KEY}
https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/subjects/{SUBJECT_ID}/bookshelves?access_token={API_KEY}
https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/subjects/{SUBJECT_ID}/journals?access_token={API_KEY}

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/bookcases/{BOOKCASE_ID}/bookshelves?access_token={API_KEY}
https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/bookcases/{BOOKCASE_ID}/journals?access_token={API_KEY}

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/bookshelves/{BOOKSHELF_ID}/journals?access_token={API_KEY}

Root Taxonomy Request

When no additional path segments are supplied, the endpoint returns the top-level taxonomy for the library: the same subject structure users see when browsing BrowZine on the web.

Example request:

https://public-api.thirdiron.com/public/v1/libraries/{Library_ID}/subjects?access_token={API_KEY}

Your response will contain subject records along with links or relationships to the next available layers beneath each subject. In practical terms, this allows an application to render a subject landing page immediately and then drill deeper as users interact with it.

How Traversal Works

The key design principle of this endpoint is that API consumers should not hit a dead end.

• A subject response can point downward to its bookcases, bookshelves, and journals, and upward to the root subjects list

• A bookcase response can point downward to its bookshelves and journals, and upward to its parent subject

• A bookshelf response can point downward to its journals, and upward to its parent bookcase or subject context

• A journals list response points back to the taxonomy level from which it was requested

Journals Responses

Journals can be requested from multiple taxonomy levels. For example, a client may ask for journals for a subject, a bookcase, or a bookshelf.

When a journals list is returned, its parent pointer reflects the taxonomy level used in the request.

• If you request journals from a subject, the journals response points back to that subject

• If you request journals from a bookcase, the journals response points back to that bookcase

• If you request journals from a bookshelf, the journals response points back to that bookshelf

This keeps traversal consistent: the client always gets a single clear “up” path based on the current context.

Implementation Example

A common implementation flow looks like this:

1. Request the root subjects list for the library

2. Display subject names in your interface

3. When a user selects a subject, follow the response links to fetch bookcases, bookshelves, or journals

4. When a user drills deeper, keep following API-provided child links

5. Use parent links in each response to support breadcrumb or back-navigation behavior

For example, a user browsing Neuroscience might move from the subjects list to a subject, then into a bookcase, then into a bookshelf, then into journals. At each stage, your application can render both the next step down and a clear route back up.

Best Practices

• Start at the root: Begin with /subjects unless you already have a specific taxonomy URL from an earlier response

• Follow links rather than assumptions: Let the API tell your client what is available beneath or above the current node

• Support upward navigation: Use parent pointers for breadcrumbs, back buttons, and contextual labels

• Expect different child combinations: Some subjects may expose bookcases and bookshelves; others may provide direct journal access depending on the taxonomy structure

• Handle paginated journals lists: Especially for broad categories, do not assume a single-page journal response

What This Endpoint Is For

This endpoint is especially useful when you want to build dynamic library experiences such as:

• Browsable subject pages on a library website

• Category-based journal navigation

• Custom “Explore by discipline” interfaces

• API-driven taxonomy pickers for other Public API++ workflows

It is also a useful companion to other API++ features, such as endpoints that return journals or new content scoped to taxonomy areas.

Quick Reference

FAQ

Questions? Email us at support@thirdiron.com for implementation help or access confirmation.