{"id":"linked-art/api/design-principles","relativePath":"linked-art/api/design-principles.md","title":"Linked Art API: Design Principles","markdown":"# Linked Art API: Design Principles\n\n**Last refreshed:** 2026-07-06\n\nSource: [Design Principles](https://linked.art/api/1.0/principles/), part of Linked Art API 1.0, published under [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/). This is a project summary; the upstream page is authoritative.\n\n## Purpose\n\nThe 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.\n\n## Core Principles\n\n1. Scope design through shared, consistent use cases.\n2. Design for international use.\n3. Make the API as simple as possible, but no simpler.\n4. Avoid dependency on specific technologies.\n5. Use REST and do not break the web.\n6. Design for JSON-LD while following Linked Open Data principles.\n7. Follow existing standards and best practices when possible.\n8. Define success rather than failure for extensibility.\n9. Do not fear the network.\n10. Solve at the right layer.\n\n## Practical Intent\n\nThe principles are adoption-oriented:\n\n- Shared use cases keep the API focused on real interoperability needs rather than speculative features.\n- Internationalization prevents language from becoming a barrier to adoption.\n- Incremental complexity lets implementers start with a minimum useful publisher and add richer patterns over time.\n- Technology neutrality allows static files, existing sites, databases, triplestores, and other backends to publish conforming records.\n- REST and web infrastructure make responses cacheable, understandable, and easy to retrieve with normal HTTP tooling.\n- JSON-LD keeps the data usable as plain JSON while preserving linked-data semantics for consumers that need RDF.\n- Standards alignment keeps Linked Art integrated with the wider cultural heritage and web ecosystem.\n- Extensibility allows implementation experiments without declaring every unrecognized extension invalid.\n\n## Trivial Implementation Requirements\n\nThe API is intentionally designed so that a conforming publisher can start simply:\n\n- Core API records can be implemented as files on disk.\n- Data files can be hand-authored as JSON.\n- Responses should be as small as possible while remaining consistent and useful.\n\nThis does not mean dynamic databases are discouraged. It means a database must not be required for a basic conforming implementation.\n\n## Consistency Across Representations\n\nThe API minimizes duplicated statements:\n\n- Each statement should appear in one response document when possible.\n- A resource referenced by many other resources should have its own response.\n- Inverse relationships are treated as the same information, not as separate mandatory assertions.\n- A relationship should normally be encoded in one direction, with inverse discovery handled by another API or query layer when needed.\n\nPerformance-oriented exceptions can exist, but they should be limited and explicit because duplicated statements can drift out of sync.\n\n## Division Of Information\n\nThe API favors maintainable response boundaries:\n\n- Partitioning and one-to-many relationships should usually point from the many to the one.\n- Large member or part lists should not make parent records huge.\n- The rule for deciding which response owns a statement should be deterministic and simple.\n- If a resource does not need incoming references and is one-to-one with its parent, it can be embedded in the parent.\n- Common embedded structures include names, identifiers, dimensions, timespans, monetary amounts, and beginning/end lifecycle structures.\n\nThis supports both hand-authored files and machine-generated API responses.\n\n## URI Requirements\n\nThe design principles keep URI handling flexible:\n\n- Embedded resources such as names and dimensions do not need their own URI unless they must be dereferenced or referenced independently.\n- API endpoint URI structure is intentionally not prescribed.\n- Consumers should treat URIs as opaque identifiers rather than inferring semantics from path segments.\n\nThis lets Linked Art be layered onto existing websites and infrastructure without forcing a single URL design.\n\n## Model Versus API Layer\n\nThe principles emphasize solving problems at the correct layer:\n\n- If the challenge is client interaction, navigation, retrieval, caching, search, or synchronization, solve it in the API layer.\n- If the challenge is describing cultural heritage entities and relationships, solve it in the model.\n\nThis boundary keeps the model semantically clean while letting the API stay pragmatic for implementation and consumption.\n\n## Meta Museum Notes\n\nMeta 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.\n\n## Test Ideas\n\n- Keep docs and endpoint fixtures from relying on URI path semantics.\n- Preserve one-direction relationship assertions unless an inverse API explicitly owns inverse discovery.\n- Keep large membership and part relationships discoverable without forcing parent records to include exhaustive inverse lists.\n- Preserve embedded name, identifier, dimension, timespan, monetary amount, and lifecycle structures when they do not need independent dereferenceable endpoints.\n- Keep JSON-LD records usable as predictable JSON without requiring RDF tooling for basic consumption.\n","sections":[{"level":2,"heading":"Purpose","anchor":"purpose"},{"level":2,"heading":"Core Principles","anchor":"core-principles"},{"level":2,"heading":"Practical Intent","anchor":"practical-intent"},{"level":2,"heading":"Trivial Implementation Requirements","anchor":"trivial-implementation-requirements"},{"level":2,"heading":"Consistency Across Representations","anchor":"consistency-across-representations"},{"level":2,"heading":"Division Of Information","anchor":"division-of-information"},{"level":2,"heading":"URI Requirements","anchor":"uri-requirements"},{"level":2,"heading":"Model Versus API Layer","anchor":"model-versus-api-layer"},{"level":2,"heading":"Meta Museum Notes","anchor":"meta-museum-notes"},{"level":2,"heading":"Test Ideas","anchor":"test-ideas"}],"html":"<h1 id=\"linked-art-api-design-principles\">Linked Art API: Design Principles</h1>\n<p><strong>Last refreshed:</strong> 2026-07-06</p>\n<p>Source: <a href=\"https://linked.art/api/1.0/principles/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">Design Principles</a>, part of Linked Art API 1.0, published under <a href=\"http://creativecommons.org/licenses/by/4.0/\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"doc-link\">CC BY 4.0</a>. This is a project summary; the upstream page is authoritative.</p>\n<h2 id=\"purpose\">Purpose</h2>\n<p>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.</p>\n<h2 id=\"core-principles\">Core Principles</h2>\n<ol><li>Scope design through shared, consistent use cases.</li></ol>\n<ol><li>Design for international use.</li></ol>\n<ol><li>Make the API as simple as possible, but no simpler.</li></ol>\n<ol><li>Avoid dependency on specific technologies.</li></ol>\n<ol><li>Use REST and do not break the web.</li></ol>\n<ol><li>Design for JSON-LD while following Linked Open Data principles.</li></ol>\n<ol><li>Follow existing standards and best practices when possible.</li></ol>\n<ol><li>Define success rather than failure for extensibility.</li></ol>\n<ol><li>Do not fear the network.</li></ol>\n<ol><li>Solve at the right layer.</li></ol>\n<h2 id=\"practical-intent\">Practical Intent</h2>\n<p>The principles are adoption-oriented:</p>\n<ul><li>Shared use cases keep the API focused on real interoperability needs rather than speculative features.</li><li>Internationalization prevents language from becoming a barrier to adoption.</li><li>Incremental complexity lets implementers start with a minimum useful publisher and add richer patterns over time.</li><li>Technology neutrality allows static files, existing sites, databases, triplestores, and other backends to publish conforming records.</li><li>REST and web infrastructure make responses cacheable, understandable, and easy to retrieve with normal HTTP tooling.</li><li>JSON-LD keeps the data usable as plain JSON while preserving linked-data semantics for consumers that need RDF.</li><li>Standards alignment keeps Linked Art integrated with the wider cultural heritage and web ecosystem.</li><li>Extensibility allows implementation experiments without declaring every unrecognized extension invalid.</li></ul>\n<h2 id=\"trivial-implementation-requirements\">Trivial Implementation Requirements</h2>\n<p>The API is intentionally designed so that a conforming publisher can start simply:</p>\n<ul><li>Core API records can be implemented as files on disk.</li><li>Data files can be hand-authored as JSON.</li><li>Responses should be as small as possible while remaining consistent and useful.</li></ul>\n<p>This does not mean dynamic databases are discouraged. It means a database must not be required for a basic conforming implementation.</p>\n<h2 id=\"consistency-across-representations\">Consistency Across Representations</h2>\n<p>The API minimizes duplicated statements:</p>\n<ul><li>Each statement should appear in one response document when possible.</li><li>A resource referenced by many other resources should have its own response.</li><li>Inverse relationships are treated as the same information, not as separate mandatory assertions.</li><li>A relationship should normally be encoded in one direction, with inverse discovery handled by another API or query layer when needed.</li></ul>\n<p>Performance-oriented exceptions can exist, but they should be limited and explicit because duplicated statements can drift out of sync.</p>\n<h2 id=\"division-of-information\">Division Of Information</h2>\n<p>The API favors maintainable response boundaries:</p>\n<ul><li>Partitioning and one-to-many relationships should usually point from the many to the one.</li><li>Large member or part lists should not make parent records huge.</li><li>The rule for deciding which response owns a statement should be deterministic and simple.</li><li>If a resource does not need incoming references and is one-to-one with its parent, it can be embedded in the parent.</li><li>Common embedded structures include names, identifiers, dimensions, timespans, monetary amounts, and beginning/end lifecycle structures.</li></ul>\n<p>This supports both hand-authored files and machine-generated API responses.</p>\n<h2 id=\"uri-requirements\">URI Requirements</h2>\n<p>The design principles keep URI handling flexible:</p>\n<ul><li>Embedded resources such as names and dimensions do not need their own URI unless they must be dereferenced or referenced independently.</li><li>API endpoint URI structure is intentionally not prescribed.</li><li>Consumers should treat URIs as opaque identifiers rather than inferring semantics from path segments.</li></ul>\n<p>This lets Linked Art be layered onto existing websites and infrastructure without forcing a single URL design.</p>\n<h2 id=\"model-versus-api-layer\">Model Versus API Layer</h2>\n<p>The principles emphasize solving problems at the correct layer:</p>\n<ul><li>If the challenge is client interaction, navigation, retrieval, caching, search, or synchronization, solve it in the API layer.</li><li>If the challenge is describing cultural heritage entities and relationships, solve it in the model.</li></ul>\n<p>This boundary keeps the model semantically clean while letting the API stay pragmatic for implementation and consumption.</p>\n<h2 id=\"meta-museum-notes\">Meta Museum Notes</h2>\n<p>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.</p>\n<h2 id=\"test-ideas\">Test Ideas</h2>\n<ul><li>Keep docs and endpoint fixtures from relying on URI path semantics.</li><li>Preserve one-direction relationship assertions unless an inverse API explicitly owns inverse discovery.</li><li>Keep large membership and part relationships discoverable without forcing parent records to include exhaustive inverse lists.</li><li>Preserve embedded name, identifier, dimension, timespan, monetary amount, and lifecycle structures when they do not need independent dereferenceable endpoints.</li><li>Keep JSON-LD records usable as predictable JSON without requiring RDF tooling for basic consumption.</li></ul>","updatedAt":"2026-07-06T00:00:00.000Z","checksum":"3ff80e8696b037a00bc6cde497a200815f756edcffb214717b367babab2cf4db","checksumPrefix":"3ff80e8696b0","anchorCount":10,"lineCount":100,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fdesign-principles.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fdesign-principles.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fdesign-principles.md"}