
<!doctype html>
<html lang="en" class="no-js">
  <head>
    
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width,initial-scale=1">
      
      
      
      
      <link rel="shortcut icon" href="../../../../assets/images/dasch-favicon.ico">
      <meta name="generator" content="mkdocs-1.1.2, mkdocs-material-6.2.8">
    
    
      
        <title>API v2 Design Overview - Knora Documentation</title>
      
    
    
      <link rel="stylesheet" href="../../../../assets/stylesheets/main.cb6bc1d0.min.css">
      
        
        <link rel="stylesheet" href="../../../../assets/stylesheets/palette.39b8e14a.min.css">
        
          
          
          <meta name="theme-color" content="#7e56c2">
        
      
    
    
    
      
        
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700%7CRoboto+Mono&display=fallback">
        <style>body,input{font-family:"Roboto",-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono",SFMono-Regular,Consolas,Menlo,monospace}</style>
      
    
    
    
      <link rel="stylesheet" href="../../../../assets/style/theme.css">
    
    
      
    
    
  </head>
  
  
    
    
    
    
    
    <body dir="ltr" data-md-color-scheme="" data-md-color-primary="deep-purple" data-md-color-accent="deep-purple">
      
  
    
    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
    <label class="md-overlay" for="__drawer"></label>
    <div data-md-component="skip">
      
        
        <a href="#api-v2-design-overview" class="md-skip">
          Skip to content
        </a>
      
    </div>
    <div data-md-component="announce">
      
    </div>
    
      

<header class="md-header" data-md-component="header">
  <nav class="md-header-nav md-grid" aria-label="Header">
    <a href="../../../.." title="Knora Documentation" class="md-header-nav__button md-logo" aria-label="Knora Documentation">
      
  <img src="../../../../assets/images/dasch-icon-white.svg" alt="logo">

    </a>
    <label class="md-header-nav__button md-icon" for="__drawer">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
    </label>
    <div class="md-header-nav__title" data-md-component="header-title">
      <div class="md-header-nav__ellipsis">
        <div class="md-header-nav__topic">
          <span class="md-ellipsis">
            Knora Documentation
          </span>
        </div>
        <div class="md-header-nav__topic">
          <span class="md-ellipsis">
            
              API v2 Design Overview
            
          </span>
        </div>
      </div>
    </div>
    
      <label class="md-header-nav__button md-icon" for="__search">
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0116 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 019.5 16 6.5 6.5 0 013 9.5 6.5 6.5 0 019.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
      </label>
      
<div class="md-search" data-md-component="search" role="dialog">
  <label class="md-search__overlay" for="__search"></label>
  <div class="md-search__inner" role="search">
    <form class="md-search__form" name="search">
      <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active" required>
      <label class="md-search__icon md-icon" for="__search">
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0116 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 019.5 16 6.5 6.5 0 013 9.5 6.5 6.5 0 019.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
      </label>
      <button type="reset" class="md-search__icon md-icon" aria-label="Clear" data-md-component="search-reset" tabindex="-1">
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"/></svg>
      </button>
    </form>
    <div class="md-search__output">
      <div class="md-search__scrollwrap" data-md-scrollfix>
        <div class="md-search-result" data-md-component="search-result">
          <div class="md-search-result__meta">
            Initializing search
          </div>
          <ol class="md-search-result__list"></ol>
        </div>
      </div>
    </div>
  </div>
</div>
    
    
  </nav>
</header>
    
    <div class="md-container" data-md-component="container">
      
      
        
          
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
  <div class="md-tabs__inner md-grid">
    <ul class="md-tabs__list">
      
        
  
  


  <li class="md-tabs__item">
    <a href="../../../.." class="md-tabs__link">
      Home
    </a>
  </li>

      
        
  
  


  
  
  
    <li class="md-tabs__item">
      <a href="../../../../01-introduction/" class="md-tabs__link">
        Introduction
      </a>
    </li>
  

      
        
  
  


  
  
  
    <li class="md-tabs__item">
      <a href="../../../../02-knora-ontologies/" class="md-tabs__link">
        Knora Ontologies
      </a>
    </li>
  

      
        
  
  


  
  
  
    

  
  
  
    <li class="md-tabs__item">
      <a href="../../../../03-apis/" class="md-tabs__link">
        APIs
      </a>
    </li>
  

  

      
        
  
  


  
  
  
    <li class="md-tabs__item">
      <a href="../../../../04-publishing-deployment/" class="md-tabs__link">
        Publishing and Deployment
      </a>
    </li>
  

      
        
  
  
    
  


  
  
  
    

  
  
  
    

  
  
  
    <li class="md-tabs__item">
      <a href="../../principles/" class="md-tabs__link md-tabs__link--active">
        Knora Internals
      </a>
    </li>
  

  

  

      
        
  
  


  
  
  
    <li class="md-tabs__item">
      <a href="../../../../06-salsah/index.md" class="md-tabs__link">
        Salsah
      </a>
    </li>
  

      
        
  
  


  
  
  
    <li class="md-tabs__item">
      <a href="../../../../07-sipi/" class="md-tabs__link">
        SIPI
      </a>
    </li>
  

      
        
  
  


  
  
  
    <li class="md-tabs__item">
      <a href="../../../../08-lucene/" class="md-tabs__link">
        Lucene
      </a>
    </li>
  

      
        
  
  


  <li class="md-tabs__item">
    <a href="../../../../faq/" class="md-tabs__link">
      Frequently Asked Questions
    </a>
  </li>

      
        
  
  


  
  
  
    <li class="md-tabs__item">
      <a href="../../../../00-release-notes/" class="md-tabs__link">
        Release Notes
      </a>
    </li>
  

      
    </ul>
  </div>
</nav>
        
      
      <main class="md-main" data-md-component="main">
        <div class="md-main__inner md-grid">
          
            
              
              <div class="md-sidebar md-sidebar--primary" data-md-component="navigation" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    



  


<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
  <label class="md-nav__title" for="__drawer">
    <a href="../../../.." title="Knora Documentation" class="md-nav__button md-logo" aria-label="Knora Documentation">
      
  <img src="../../../../assets/images/dasch-icon-white.svg" alt="logo">

    </a>
    Knora Documentation
  </label>
  
  <ul class="md-nav__list" data-md-scrollfix>
    
      
      
      

  
  
  
    <li class="md-nav__item">
      <a href="../../../.." class="md-nav__link">
        Home
      </a>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-2" type="checkbox" id="nav-2" >
      
      <label class="md-nav__link" for="nav-2">
        Introduction
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Introduction" data-md-level="1">
        <label class="md-nav__title" for="nav-2">
          <span class="md-nav__icon md-icon"></span>
          Introduction
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../01-introduction/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../01-introduction/what-is-knora/" class="md-nav__link">
        What is Knora?
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../01-introduction/data-formats/" class="md-nav__link">
        Data Formats in Knora
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../01-introduction/standoff-rdf/" class="md-nav__link">
        Standoff/RDF Text Markup
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../01-introduction/example-project/" class="md-nav__link">
        An Example Project
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-3" type="checkbox" id="nav-3" >
      
      <label class="md-nav__link" for="nav-3">
        Knora Ontologies
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Knora Ontologies" data-md-level="1">
        <label class="md-nav__title" for="nav-3">
          <span class="md-nav__icon md-icon"></span>
          Knora Ontologies
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../02-knora-ontologies/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../02-knora-ontologies/introduction/" class="md-nav__link">
        Introduction
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../02-knora-ontologies/knora-base/" class="md-nav__link">
        The Knora Base Ontology
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../02-knora-ontologies/salsah-gui/" class="md-nav__link">
        The SALSAH GUI Ontology
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-4" type="checkbox" id="nav-4" >
      
      <label class="md-nav__link" for="nav-4">
        APIs
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="APIs" data-md-level="1">
        <label class="md-nav__title" for="nav-4">
          <span class="md-nav__icon md-icon"></span>
          APIs
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-4-1" type="checkbox" id="nav-4-1" >
      
      <label class="md-nav__link" for="nav-4-1">
        The Knora APIs
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="The Knora APIs" data-md-level="2">
        <label class="md-nav__title" for="nav-4-1">
          <span class="md-nav__icon md-icon"></span>
          The Knora APIs
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/feature-toggles/" class="md-nav__link">
        Feature Toggles
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
            
  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-4-2" type="checkbox" id="nav-4-2" >
      
      <label class="md-nav__link" for="nav-4-2">
        API V1
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="API V1" data-md-level="2">
        <label class="md-nav__title" for="nav-4-2">
          <span class="md-nav__icon md-icon"></span>
          API V1
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/introduction/" class="md-nav__link">
        Introduction
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/authentication/" class="md-nav__link">
        Authentication
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/reading-and-searching-resources/" class="md-nav__link">
        Reading and Searching Resources
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/xml-to-standoff-mapping/" class="md-nav__link">
        XML to Standoff Mapping
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/adding-resources/" class="md-nav__link">
        Adding Resources
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/reading-and-searching-resources/" class="md-nav__link">
        Reading and Searching Resources
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/reading-values/" class="md-nav__link">
        Reading Values
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/adding-values/" class="md-nav__link">
        Adding Values
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/changing-values/" class="md-nav__link">
        Changing Values
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v1/delete-resources-and-values/" class="md-nav__link">
        Deleting Resources and Values
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
            
  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-4-3" type="checkbox" id="nav-4-3" >
      
      <label class="md-nav__link" for="nav-4-3">
        API V2
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="API V2" data-md-level="2">
        <label class="md-nav__title" for="nav-4-3">
          <span class="md-nav__icon md-icon"></span>
          API V2
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/introduction/" class="md-nav__link">
        Introduction
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/authentication/" class="md-nav__link">
        Authentication
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/knora-iris/" class="md-nav__link">
        Knora IRIs
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/metadata/" class="md-nav__link">
        Metadata
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/reading-and-searching-resources/" class="md-nav__link">
        Reading and Searching Resources
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/reading-user-permissions/" class="md-nav__link">
        Reading the User's Permissions on Resources and Values
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/getting-lists/" class="md-nav__link">
        Getting Lists
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/xml-to-standoff-mapping/" class="md-nav__link">
        XML to Standoff Mapping
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/query-language/" class="md-nav__link">
        Gravsearch - Virtual Graph Search
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/editing-resources/" class="md-nav__link">
        Editing Resources
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/editing-values/" class="md-nav__link">
        Editing Values
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/ontology-information/" class="md-nav__link">
        Querying, Creating, and Updating Ontologies
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/tei-xml/" class="md-nav__link">
        TEI/XML
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-v2/permalinks/" class="md-nav__link">
        Permalinks
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
            
  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-4-4" type="checkbox" id="nav-4-4" >
      
      <label class="md-nav__link" for="nav-4-4">
        Admin API
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Admin API" data-md-level="2">
        <label class="md-nav__title" for="nav-4-4">
          <span class="md-nav__icon md-icon"></span>
          Admin API
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/introduction/" class="md-nav__link">
        Introduction
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/overview/" class="md-nav__link">
        Overview
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/users/" class="md-nav__link">
        Users Endpoint
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/projects/" class="md-nav__link">
        Projects Endpoint
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/groups/" class="md-nav__link">
        Groups Endpoint
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/lists/" class="md-nav__link">
        Lists Endpoint
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/lists_new-list-admin-routes_v1/" class="md-nav__link">
        New Lists Endpoint
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/permissions/" class="md-nav__link">
        Permissions Endpoint
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-admin/stores/" class="md-nav__link">
        Stores Endpoint
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
            
  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-4-5" type="checkbox" id="nav-4-5" >
      
      <label class="md-nav__link" for="nav-4-5">
        Util API
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Util API" data-md-level="2">
        <label class="md-nav__title" for="nav-4-5">
          <span class="md-nav__icon md-icon"></span>
          Util API
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-util/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-util/health/" class="md-nav__link">
        Health
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../03-apis/api-util/version/" class="md-nav__link">
        Version
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-5" type="checkbox" id="nav-5" >
      
      <label class="md-nav__link" for="nav-5">
        Publishing and Deployment
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Publishing and Deployment" data-md-level="1">
        <label class="md-nav__title" for="nav-5">
          <span class="md-nav__icon md-icon"></span>
          Publishing and Deployment
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../04-publishing-deployment/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../04-publishing-deployment/publishing/" class="md-nav__link">
        Publishing
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../04-publishing-deployment/getting-started/" class="md-nav__link">
        Getting Started with Knora
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../04-publishing-deployment/configuration/" class="md-nav__link">
        Configuration
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../04-publishing-deployment/updates/" class="md-nav__link">
        Updating Repositories when Upgrading Knora
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
    
  
  
    
    <li class="md-nav__item md-nav__item--active md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-6" type="checkbox" id="nav-6" checked>
      
      <label class="md-nav__link" for="nav-6">
        Knora Internals
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Knora Internals" data-md-level="1">
        <label class="md-nav__title" for="nav-6">
          <span class="md-nav__icon md-icon"></span>
          Knora Internals
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
    
  
  
    
    <li class="md-nav__item md-nav__item--active md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-6-1" type="checkbox" id="nav-6-1" checked>
      
      <label class="md-nav__link" for="nav-6-1">
        Design
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Design" data-md-level="2">
        <label class="md-nav__title" for="nav-6-1">
          <span class="md-nav__icon md-icon"></span>
          Design
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-6-1-1" type="checkbox" id="nav-6-1-1" >
      
      <label class="md-nav__link" for="nav-6-1-1">
        Knora Design Principles
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Knora Design Principles" data-md-level="3">
        <label class="md-nav__title" for="nav-6-1-1">
          <span class="md-nav__icon md-icon"></span>
          Knora Design Principles
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/design-overview/" class="md-nav__link">
        Design Overview
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/futures-with-akka/" class="md-nav__link">
        Futures with Akka
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/http-module/" class="md-nav__link">
        HTTP Module
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/store-module/" class="md-nav__link">
        Store Module
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/triplestore-updates/" class="md-nav__link">
        Triplestore Updates
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/consistency-checking/" class="md-nav__link">
        Consistency Checking
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/authentication/" class="md-nav__link">
        Authentication
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/feature-toggles/" class="md-nav__link">
        Feature Toggles
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../principles/rdf-api/" class="md-nav__link">
        RDF Processing API
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
            
  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-6-1-2" type="checkbox" id="nav-6-1-2" >
      
      <label class="md-nav__link" for="nav-6-1-2">
        API V1 Design
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="API V1 Design" data-md-level="3">
        <label class="md-nav__title" for="nav-6-1-2">
          <span class="md-nav__icon md-icon"></span>
          API V1 Design
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../api-v1/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../api-v1/how-to-add-a-route/" class="md-nav__link">
        How to Add an API v1 Route
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../api-v1/json/" class="md-nav__link">
        JSON in API v1
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
            
  
  
    
  
  
    
    <li class="md-nav__item md-nav__item--active md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-6-1-3" type="checkbox" id="nav-6-1-3" checked>
      
      <label class="md-nav__link" for="nav-6-1-3">
        API V2 Design
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="API V2 Design" data-md-level="3">
        <label class="md-nav__title" for="nav-6-1-3">
          <span class="md-nav__icon md-icon"></span>
          API V2 Design
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
    
  
  
    <li class="md-nav__item md-nav__item--active">
      
      <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
      
        
      
      
        <label class="md-nav__link md-nav__link--active" for="__toc">
          API v2 Design Overview
          <span class="md-nav__icon md-icon"></span>
        </label>
      
      <a href="./" class="md-nav__link md-nav__link--active">
        API v2 Design Overview
      </a>
      
        
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
  
  
    
  
  
    <label class="md-nav__title" for="__toc">
      <span class="md-nav__icon md-icon"></span>
      Table of contents
    </label>
    <ul class="md-nav__list" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#general-principles" class="md-nav__link">
    General Principles
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#api-schemas" class="md-nav__link">
    API Schemas
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#implementation" class="md-nav__link">
    Implementation
  </a>
  
    <nav class="md-nav" aria-label="Implementation">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#json-ld-parsing-and-formatting" class="md-nav__link">
    JSON-LD Parsing and Formatting
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#generation-of-other-rdf-formats" class="md-nav__link">
    Generation of Other RDF Formats
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#operation-wrappers" class="md-nav__link">
    Operation Wrappers
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#smart-iris" class="md-nav__link">
    Smart IRIs
  </a>
  
    <nav class="md-nav" aria-label="Smart IRIs">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#usage" class="md-nav__link">
    Usage
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#implementation_1" class="md-nav__link">
    Implementation
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
    </ul>
  
</nav>
      
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../ontology-schemas/" class="md-nav__link">
        Ontology Schemas
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../smart-iris/" class="md-nav__link">
        Smart IRIs
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../content-wrappers/" class="md-nav__link">
        Content Wrappers
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../how-to-add-a-route/" class="md-nav__link">
        How to Add an API v2 Route
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../json-ld/" class="md-nav__link">
        JSON-LD Parsing and Formatting
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../ontology-management/" class="md-nav__link">
        Ontology Management
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../sipi/" class="md-nav__link">
        Knora and Sipi
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../gravsearch/" class="md-nav__link">
        Gravsearch Design
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../standoff/" class="md-nav__link">
        Standoff Markup
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../ark/" class="md-nav__link">
        Archival Resource Key (ARK) Identifiers
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../query-design/" class="md-nav__link">
        SPARQL Query Design
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
            
  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-6-1-4" type="checkbox" id="nav-6-1-4" >
      
      <label class="md-nav__link" for="nav-6-1-4">
        Admin API Design
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Admin API Design" data-md-level="3">
        <label class="md-nav__title" for="nav-6-1-4">
          <span class="md-nav__icon md-icon"></span>
          Admin API Design
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../api-admin/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../api-admin/administration/" class="md-nav__link">
        Administration
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
            
  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-6-2" type="checkbox" id="nav-6-2" >
      
      <label class="md-nav__link" for="nav-6-2">
        Development
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Development" data-md-level="2">
        <label class="md-nav__title" for="nav-6-2">
          <span class="md-nav__icon md-icon"></span>
          Development
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/overview/" class="md-nav__link">
        Overview
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/building-and-running/" class="md-nav__link">
        Build and Running
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/intellij-config/" class="md-nav__link">
        Setup IntelliJ for development of Knora
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/bazel/" class="md-nav__link">
        Bazel Notes
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/testing/" class="md-nav__link">
        Testing
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/docker-cheat-sheet/" class="md-nav__link">
        Docker Cheat Sheet
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/monitoring/" class="md-nav__link">
        Monitoring Knora
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/profiling/" class="md-nav__link">
        Profiling Knora
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/docker-compose/" class="md-nav__link">
        Starting the Knora-Stack inside Docker Container
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/updating-repositories/" class="md-nav__link">
        Updating Repositories
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/generating-client-test-data/" class="md-nav__link">
        Generating Client Test Data
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/graphdb/" class="md-nav__link">
        Starting GraphDB
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../development/third-party/" class="md-nav__link">
        Third-Party Dependencies
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-7" type="checkbox" id="nav-7" >
      
      <label class="md-nav__link" for="nav-7">
        Salsah
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Salsah" data-md-level="1">
        <label class="md-nav__title" for="nav-7">
          <span class="md-nav__icon md-icon"></span>
          Salsah
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../06-salsah/index.md" class="md-nav__link">
        Index
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-8" type="checkbox" id="nav-8" >
      
      <label class="md-nav__link" for="nav-8">
        SIPI
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="SIPI" data-md-level="1">
        <label class="md-nav__title" for="nav-8">
          <span class="md-nav__icon md-icon"></span>
          SIPI
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../07-sipi/" class="md-nav__link">
        Index
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../07-sipi/setup-sipi-for-knora/" class="md-nav__link">
        Setting Up Sipi for Knora
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../07-sipi/sipi-and-knora/" class="md-nav__link">
        Interaction between Sipi and Knora
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-9" type="checkbox" id="nav-9" >
      
      <label class="md-nav__link" for="nav-9">
        Lucene
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Lucene" data-md-level="1">
        <label class="md-nav__title" for="nav-9">
          <span class="md-nav__icon md-icon"></span>
          Lucene
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../08-lucene/" class="md-nav__link">
        Overview
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../08-lucene/lucene-query-parser-syntax/" class="md-nav__link">
        Lucene Query Parser Syntax
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
      
      
      

  
  
  
    <li class="md-nav__item">
      <a href="../../../../faq/" class="md-nav__link">
        Frequently Asked Questions
      </a>
    </li>
  

    
      
      
      

  
  
  
    
    <li class="md-nav__item md-nav__item--nested">
      
      
        <input class="md-nav__toggle md-toggle" data-md-toggle="nav-11" type="checkbox" id="nav-11" >
      
      <label class="md-nav__link" for="nav-11">
        Release Notes
        <span class="md-nav__icon md-icon"></span>
      </label>
      <nav class="md-nav" aria-label="Release Notes" data-md-level="1">
        <label class="md-nav__title" for="nav-11">
          <span class="md-nav__icon md-icon"></span>
          Release Notes
        </label>
        <ul class="md-nav__list" data-md-scrollfix>
          
          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/" class="md-nav__link">
        Overview
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/migration/" class="md-nav__link">
        Migration Notes
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/next/" class="md-nav__link">
        Next Release
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v1.1.0/" class="md-nav__link">
        v1.1.0
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v1.2.0/" class="md-nav__link">
        v1.2.0
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v1.3.0/" class="md-nav__link">
        v1.3.0
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v1.4.0/" class="md-nav__link">
        v1.4.0
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v1.5.0/" class="md-nav__link">
        v1.5.0
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v1.6.0/" class="md-nav__link">
        v1.6.0
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v1.7.0/" class="md-nav__link">
        v1.7.0
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v2.x.x/" class="md-nav__link">
        v2.x.x
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v3.x.x/" class="md-nav__link">
        v3.x.x
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v4.x.x/" class="md-nav__link">
        v4.x.x
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v5.x.x/" class="md-nav__link">
        v5.x.x
      </a>
    </li>
  

          
            
  
  
  
    <li class="md-nav__item">
      <a href="../../../../00-release-notes/v6.x.x/" class="md-nav__link">
        v6.x.x
      </a>
    </li>
  

          
        </ul>
      </nav>
    </li>
  

    
  </ul>
</nav>
                  </div>
                </div>
              </div>
            
            
              
              <div class="md-sidebar md-sidebar--secondary" data-md-component="toc" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
  
  
    
  
  
    <label class="md-nav__title" for="__toc">
      <span class="md-nav__icon md-icon"></span>
      Table of contents
    </label>
    <ul class="md-nav__list" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#general-principles" class="md-nav__link">
    General Principles
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#api-schemas" class="md-nav__link">
    API Schemas
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#implementation" class="md-nav__link">
    Implementation
  </a>
  
    <nav class="md-nav" aria-label="Implementation">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#json-ld-parsing-and-formatting" class="md-nav__link">
    JSON-LD Parsing and Formatting
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#generation-of-other-rdf-formats" class="md-nav__link">
    Generation of Other RDF Formats
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#operation-wrappers" class="md-nav__link">
    Operation Wrappers
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#smart-iris" class="md-nav__link">
    Smart IRIs
  </a>
  
    <nav class="md-nav" aria-label="Smart IRIs">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#usage" class="md-nav__link">
    Usage
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#implementation_1" class="md-nav__link">
    Implementation
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
    </ul>
  
</nav>
                  </div>
                </div>
              </div>
            
          
          <div class="md-content">
            <article class="md-content__inner md-typeset">
              
                
                
                <!---
Copyright © 2015-2021 the contributors (see Contributors.md).

This file is part of Knora.

Knora is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Knora is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public
License along with Knora.  If not, see <http://www.gnu.org/licenses/>.
-->

<h1 id="api-v2-design-overview">API v2 Design Overview</h1>
<h2 id="general-principles">General Principles</h2>
<ul>
<li>Knora API v2 requests and responses are RDF documents. Any API v2
    response can be returned as <a href="https://json-ld.org/spec/latest/json-ld/">JSON-LD</a>,
    <a href="https://www.w3.org/TR/turtle/">Turtle</a>,
    or <a href="https://www.w3.org/TR/rdf-syntax-grammar/">RDF/XML</a>.</li>
<li>Each class or property used in a request or response has a
    definition in an ontology, which Knora can serve.</li>
<li>Response formats are reused for different requests whenever
    possible, to minimise the number of different response formats a
    client has to handle. For example, any request for one or more
    resources (such as a search result, or a request for one specific
    resource) returns a response in the same format.</li>
<li>Response size is limited by design. Large amounts of data must be
    retrieved by requesting small pages of data, one after the other.</li>
<li>Responses that provide data are distinct from responses that provide
    definitions (i.e. ontology entities). Data responses indicate which
    types are used, and the client can request information about these
    types separately.</li>
</ul>
<h2 id="api-schemas">API Schemas</h2>
<p>The types used in the triplestore are not exposed directly in the API.
Instead, they are mapped onto API 'schemas'. Two schemas are currently
provided.</p>
<ul>
<li>A complex schema, which is suitable both for reading and for editing
    data. The complex schema represents values primarily as complex
    objects.</li>
<li>A simple schema, which is suitable for reading data but not for
    editing it. The simple schema facilitates interoperability between
    Knora ontologies and non-Knora ontologies, since it represents
    values primarily as literals.</li>
</ul>
<p>Each schema has its own type IRIs, which are derived from the ones used
in the triplestore. For details of these different IRI formats, see
<a href="../../../../03-apis/api-v2/knora-iris/">Knora IRIs</a>.</p>
<h2 id="implementation">Implementation</h2>
<h3 id="json-ld-parsing-and-formatting">JSON-LD Parsing and Formatting</h3>
<p>Each API response is represented by a class that extends
<code>KnoraResponseV2</code>, which has a method <code>toJsonLDDocument</code> that specifies
the target schema. It is currently up to each route to determine what
the appropriate response schema should be. Some routes will support only
one response schema. Others will allow the client to choose, and there
will be one or more standard ways for the client to specify the desired
response schema.</p>
<p>A route calls <code>RouteUtilV2.runRdfRoute</code>, passing a request message and
a response schema. When <code>RouteUtilV2</code> gets the response message from the
responder, it calls <code>toJsonLDDocument</code> on it, specifying that schema.
The response message returns a <code>JsonLDDocument</code>, which is a simple data
structure that is then converted to Java objects and passed to the
JSON-LD Java library for formatting. In general, <code>toJsonLDDocument</code> is
implemented in two stages: first the object converts itself to the
target schema, and then the resulting object is converted to a
<code>JsonLDDocument</code>.</p>
<p>A route that receives JSON-LD requests should use
<code>JsonLDUtil.parseJsonLD</code> to convert each request to a <code>JsonLDDocument</code>.</p>
<h3 id="generation-of-other-rdf-formats">Generation of Other RDF Formats</h3>
<p><code>RouteUtilV2.runRdfRoute</code> implements
<a href="https://tools.ietf.org/html/rfc7231#section-5.3.2">HTTP content negotiation</a>, and converts JSON-LD
responses into <a href="https://www.w3.org/TR/turtle/">Turtle</a>
or <a href="https://www.w3.org/TR/rdf-syntax-grammar/">RDF/XML</a> as appropriate.</p>
<h3 id="operation-wrappers">Operation Wrappers</h3>
<p>Whenever possible, the same data structures are used for input and
output. Often more data is available in output than in input. For
example, when a value is read from the triplestore, its IRI is
available, but when it is being created, it does not yet have an IRI. In
such cases, there is a class like <code>ValueContentV2</code>, which represents the
data that is used both for input and for output. When a value is read, a
<code>ValueContentV2</code> is wrapped in a <code>ReadValueV2</code>, which additionally
contains the value's IRI. When a value is created, it is wrapped in a
<code>CreateValueV2</code>, which has the resource IRI and the property IRI, but
not the value IRI.</p>
<p>A <code>Read*</code> wrapper can be wrapped in another <code>Read*</code> wrapper; for
example, a <code>ReadResourceV2</code> contains <code>ReadValueV2</code> objects.</p>
<p>Each <code>*Content*</code> class should extend <code>KnoraContentV2</code> and thus have a
<code>toOntologySchema</code> method or converting itself between internal and
external schemas, in either direction.</p>
<p>Each <code>Read*</code> wrapper class should have a method for converting itself to
JSON-LD in a particular external schema. If the <code>Read*</code> wrapper is a
<code>KnoraResponseV2</code>, this method is <code>toJsonLDDocument</code>.</p>
<h3 id="smart-iris">Smart IRIs</h3>
<h4 id="usage">Usage</h4>
<p>The <code>SmartIri</code> trait can be used to parse and validate IRIs, and in
particular for converting Knora type IRIs between internal and external
schemas. It validates each IRI it parses. To use it, import the
following:</p>
<pre><code class="language-scala">import org.knora.webapi.messages.{SmartIri, StringFormatter}
import org.knora.webapi.messages.IriConversions._
</code></pre>
<p>Ensure that an implicit instance of <code>StringFormatter</code> is in scope:</p>
<pre><code class="language-scala">implicit val stringFormatter: StringFormatter = StringFormatter.getGeneralInstance
</code></pre>
<p>Then, if <code>iriStr</code> is a string representing an IRI, you can can convert
it to a <code>SmartIri</code> like this:</p>
<pre><code class="language-scala">val iri: SmartIri = iriStr.toSmartIri
</code></pre>
<p>If the IRI came from a request, use this method to throw a specific
exception if the IRI is invalid:</p>
<pre><code class="language-scala">val iri: SmartIri = iriStr.toSmartIriWithErr(
    () =&gt; throw BadRequestException(s&quot;Invalid IRI: $iriStr&quot;)
)
</code></pre>
<p>You can then use methods such as <code>SmartIri.isKnoraApiV2EntityIri</code> and
<code>SmartIri.getProjectCode</code> to obtain information about the IRI. To
convert it to another schema, call <code>SmartIri.toOntologySchema</code>.
Converting a non-Knora IRI returns the same IRI.</p>
<p>If the IRI represents a Knora internal value class such as
<code>knora-base:TextValue</code>, converting it to the <code>ApiV2Simple</code> schema will
return the corresponding simplified type, such as <code>xsd:string</code>. But this
conversion is not performed in the other direction (external to
internal), since this would require knowledge of the context in which
the IRI is being used.</p>
<p>The performance penalty for using a <code>SmartIri</code> instead of a string is
very small. Instances are automatically cached once they are
constructed. Parsing and caching a <code>SmartIri</code> instance takes about 10-20
µs, and retrieving a cached <code>SmartIri</code> takes about 1 µs.</p>
<p>There is no advantage to using <code>SmartIri</code> for data IRIs, since they are
not schema-specific (and are not cached). If a data IRI has been
received from a client request, it is better just to validate it using
<code>StringFormatter.validateAndEscapeIri</code>.</p>
<h4 id="implementation_1">Implementation</h4>
<p>The smart IRI implementation, <code>SmartIriImpl</code>, is nested in the
<code>StringFormatter</code> class, because it uses Knora's
hostname, which isn't available until the Akka ActorSystem has started.
However, this means that the type of a <code>SmartIriImpl</code> instance is
dependent on the instance of <code>StringFormatter</code> that constructed it.
Therefore, instances of <code>SmartIriImpl</code> created by different instances of
<code>StringFormatter</code> can't be compared directly.</p>
<p>There are in fact two instances of <code>StringFormatter</code>:</p>
<ul>
<li>one returned by <code>StringFormatter.getGeneralInstance</code> which is
    available after Akka has started and has the API server's hostname
    (and can therefore provide <code>SmartIri</code> instances capable of parsing
    IRIs containing that hostname). This instance is used throughout the
    Knora API server.</li>
<li>one returned by <code>StringFormatter.getInstanceForConstantOntologies</code>,
    which is available before Akka has started, and is used only by the
    hard-coded constant <code>knora-api</code> ontologies.</li>
</ul>
<p>This is the reason for the existence of the <code>SmartIri</code> trait, which is a
top-level definition and has its own <code>equals</code> and <code>hashCode</code> methods.
Instances of <code>SmartIri</code> can thus be compared (e.g. to use them as unique
keys in collections), regardless of which instance of <code>StringFormatter</code>
created them.</p>
                
              
              
                


              
            </article>
          </div>
        </div>
      </main>
      
        
<footer class="md-footer">
  
    <div class="md-footer-nav">
      <nav class="md-footer-nav__inner md-grid" aria-label="Footer">
        
          <a href="../" class="md-footer-nav__link md-footer-nav__link--prev" rel="prev">
            <div class="md-footer-nav__button md-icon">
              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
            </div>
            <div class="md-footer-nav__title">
              <div class="md-ellipsis">
                <span class="md-footer-nav__direction">
                  Previous
                </span>
                Index
              </div>
            </div>
          </a>
        
        
          <a href="../ontology-schemas/" class="md-footer-nav__link md-footer-nav__link--next" rel="next">
            <div class="md-footer-nav__title">
              <div class="md-ellipsis">
                <span class="md-footer-nav__direction">
                  Next
                </span>
                Ontology Schemas
              </div>
            </div>
            <div class="md-footer-nav__button md-icon">
              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg>
            </div>
          </a>
        
      </nav>
    </div>
  
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      <div class="md-footer-copyright">
        
        Made with
        <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
          Material for MkDocs
        </a>
      </div>
      
    </div>
  </div>
</footer>
      
    </div>
    
      <script src="../../../../assets/javascripts/vendor.18f0862e.min.js"></script>
      <script src="../../../../assets/javascripts/bundle.994580cf.min.js"></script><script id="__lang" type="application/json">{"clipboard.copy": "Copy to clipboard", "clipboard.copied": "Copied to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.placeholder": "Type to start searching", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.term.missing": "Missing"}</script>
      
      <script>
        app = initialize({
          base: "../../../..",
          features: ['navigation.tabs'],
          search: Object.assign({
            worker: "../../../../assets/javascripts/worker/search.9c0e82ba.min.js"
          }, typeof search !== "undefined" && search)
        })
      </script>
      
    
  </body>
</html>