Linked Art API: Design Principles

Last refreshed: 2026-07-06

Source: Design Principles, part of Linked Art API 1.0, published under CC BY 4.0. This is a project summary; the upstream page is authoritative.

Purpose

The Linked Art API design principles are derived from IIIF design patterns and adapt them for cultural heritage linked data APIs. They explain why the API favors practical use cases, predictable JSON-LD, web-native retrieval, small and consistent response documents, opaque URIs, and clear boundaries between the semantic model and API interaction layer.

Core Principles

1. Scope design through shared, consistent use cases.

1. Design for international use.

1. Make the API as simple as possible, but no simpler.

1. Avoid dependency on specific technologies.

1. Use REST and do not break the web.

1. Design for JSON-LD while following Linked Open Data principles.

1. Follow existing standards and best practices when possible.

1. Define success rather than failure for extensibility.

1. Do not fear the network.

1. Solve at the right layer.

Practical Intent

The principles are adoption-oriented:

• Shared use cases keep the API focused on real interoperability needs rather than speculative features.
• Internationalization prevents language from becoming a barrier to adoption.
• Incremental complexity lets implementers start with a minimum useful publisher and add richer patterns over time.
• Technology neutrality allows static files, existing sites, databases, triplestores, and other backends to publish conforming records.
• REST and web infrastructure make responses cacheable, understandable, and easy to retrieve with normal HTTP tooling.
• JSON-LD keeps the data usable as plain JSON while preserving linked-data semantics for consumers that need RDF.
• Standards alignment keeps Linked Art integrated with the wider cultural heritage and web ecosystem.
• Extensibility allows implementation experiments without declaring every unrecognized extension invalid.

Trivial Implementation Requirements

The API is intentionally designed so that a conforming publisher can start simply:

• Core API records can be implemented as files on disk.
• Data files can be hand-authored as JSON.
• Responses should be as small as possible while remaining consistent and useful.

This does not mean dynamic databases are discouraged. It means a database must not be required for a basic conforming implementation.

Consistency Across Representations

The API minimizes duplicated statements:

• Each statement should appear in one response document when possible.
• A resource referenced by many other resources should have its own response.
• Inverse relationships are treated as the same information, not as separate mandatory assertions.
• A relationship should normally be encoded in one direction, with inverse discovery handled by another API or query layer when needed.

Performance-oriented exceptions can exist, but they should be limited and explicit because duplicated statements can drift out of sync.

Division Of Information

The API favors maintainable response boundaries:

• Partitioning and one-to-many relationships should usually point from the many to the one.
• Large member or part lists should not make parent records huge.
• The rule for deciding which response owns a statement should be deterministic and simple.
• If a resource does not need incoming references and is one-to-one with its parent, it can be embedded in the parent.
• Common embedded structures include names, identifiers, dimensions, timespans, monetary amounts, and beginning/end lifecycle structures.

This supports both hand-authored files and machine-generated API responses.

URI Requirements

The design principles keep URI handling flexible:

• Embedded resources such as names and dimensions do not need their own URI unless they must be dereferenced or referenced independently.
• API endpoint URI structure is intentionally not prescribed.
• Consumers should treat URIs as opaque identifiers rather than inferring semantics from path segments.

This lets Linked Art be layered onto existing websites and infrastructure without forcing a single URL design.

Model Versus API Layer

The principles emphasize solving problems at the correct layer:

• If the challenge is client interaction, navigation, retrieval, caching, search, or synchronization, solve it in the API layer.
• If the challenge is describing cultural heritage entities and relationships, solve it in the model.

This boundary keeps the model semantically clean while letting the API stay pragmatic for implementation and consumption.

Meta Museum Notes

Meta Museum already follows these principles in several project decisions: records stay Linked Art JSON-LD at the boundary, route handlers preserve web-native GET behavior, docs and exports are discoverable through public API surfaces, dataset and activity feeds avoid invented evidence, and canonical URI handling stays opaque. The principle note gives future implementers a compact checklist for deciding when to embed, when to mint dereferenceable records, when to avoid inverse duplication, and when an implementation concern belongs in API infrastructure rather than the semantic model.

Test Ideas

• Keep docs and endpoint fixtures from relying on URI path semantics.
• Preserve one-direction relationship assertions unless an inverse API explicitly owns inverse discovery.
• Keep large membership and part relationships discoverable without forcing parent records to include exhaustive inverse lists.
• Preserve embedded name, identifier, dimension, timespan, monetary amount, and lifecycle structures when they do not need independent dereferenceable endpoints.
• Keep JSON-LD records usable as predictable JSON without requiring RDF tooling for basic consumption.