Plans for Knora API v2¶

Naming
Structure
Redundancy
Efficiency
Suitability for non-GUI applications
Working with multiple projects
Annotating values
Typing
JSON-LD

Naming ¶

In API v1, the same data types are named inconsistently (resinfo, res_info) or unclearly (value_restype is actually a label). Version 2 should adopt a clear, consistent naming convention.

API v1 sometimes uses parallel array structures to represent multiple complex objects, e.g. the values of resource properties or the items in a resource’s context. Version 2 should use nested structures instead.

Redundancy ¶

Some information in API v1 is presented redundantly, e.g. resinfo and resdata, and the __location__ property. This should be cleaned up.

Efficiency ¶

Some queries, like the resource context query, produce so much data that they cannot be made efficient. We should consider breaking up these API calls into smaller chunks.

It should be possible to customise GET requests so that they return only as much data as the user wants. For example, in Fedora 4’s equivalent of the resources route with reqtype=full, you can specify whether you want child resources and incoming references. This would enable clients to request only the information they actually need, improving performance and reducing server load.

Suitability for non-GUI applications ¶

When returning the ‘full’ information about a resource, the API currently includes valueless properties to reflect the possible properties in the resource type (if a property has no value, or only has values that the user isn’t allowed to see), unless a property already has a value that the user isn’t allowed to see, and its cardinality is MustHaveOne or MayHaveOne. This makes sense from the point of a GUI: the valueless properties are there to indicate that the user could add values for those properties. If a property already has a value and its cardinality is MustHaveOne or MayHaveOne, the user can’t add a value for it, so there is no reason to include it.

In version 2, it might make more sense to separate information about resource types from information about resources (rather than mixing these two kinds of information together in one API response), and to separate displaying a resource from indicating which properties a particular user can add.

Working with multiple projects ¶

The user will be able to choose which project to use for an update.

We will handle the case where Project A defines a resource class X, and Project B declares a resource class Y with additional properties, asserting that X is a subclass of Y, so that users in Project B can add these extra properties to resources that already exist in Project A. Users in project A will want to be able to ignore the extra properties from Y, or optionally see and use them.

The ontology responder will distinguish between definitions in the active project’s named graph and definitions added elsewhere, so the user can choose to see just what’s defined in their own project or to include definitions from elsewhere.

Annotating values ¶

In API v1, only resources can be annotated. In v2, it will also be possible to annotate values.

Typing ¶

Each data item should have a consistent data type. In an JSON object, the same name should always contain a value of the same type. Numbers should be represented as numbers rather than as strings.

JSON-LD ¶

Consider using JSON-LD to specify data types and semantics within API responses, instead of providing separate JSON schemas.

The basic idea is just that your API can return JSON like this:

{
  "book": {
    "id": "http://data.knora.org/c5058f3a"
    "title": "Zeitglöcklein des Lebens und Leidens Christi"
  }
}

and it can also include a “context” (which can be embedded in the same JSON, or provided as the URL of a separate JSON document) specifying that book is an incunabula:book, and that title means dc:title. So everything in an API response can have semantics and type information specified. The idea is that the keys in the JSON stay short and readable, so someone writing a simple browser-based client can write book.title in JavaScript and it will work. At the same time, a more complex, automated client can easily get the semantic and type information.