Generating client libraries

Writing client code that works with an HTTP-based API is generally a lot of work. Therefore, such APIs often have client libraries in different programming languages, which wrap the HTTP operations in a more convenient language-specific API. We would like to have client libraries that wrap the Knora APIs, especially in TypeScript and Python. But maintaining such libraries is also a lot of work: when the API changes, the libraries have to change. We would therefore like to automatically generate the parts of these libraries that are most likely to change over time.

Most of the information we need to generate such code is already in the Knora API ontologies, so the first step is to make a code generation framework that can generate, say, TypeScript code from ontology definitions.

Andreas Aeschlimann has already developed the basis of a TypeScript client library for Knora.

So far, it focuses on the Knora admin API, and contains class definitions that correspond to definitions in the Knora admin API ontology. I’m working on generating these definitions automatically, so that when the admin API ontology changes, the corresponding TypeScript class definitions can be regenerated accordingly. The generated code could be put in a GitHub repository so it would be easily accessible to developers.

Work in progress is in Knora PR 1259.

The admin API is a good place to start, because it uses plain JSON, rather than JSON-LD, which is used in the Knora API v2.

Once that works, the next steps are:

  • Support JSON-LD and Knora API v2.
  • Support Python.
  • Generate project-specific library code. This way, a project with a class like Book could get an automatically generated Book class in TypeScript.
1 Like

With PR 1259, we have a proof-of-concept for generating the parts of client libraries that have to change when Knora changes. It generates functions and class definitions for use with @andreas’s knora-api-js-lib, covering most of the Knora admin API. This is straightforward because the classes in the admin API are built-in rather than project-specific.

@lrosenth has also started a library called knora-jsonld-simplify, aimed at wrapping Knora API v2. The idea here is that there’s a TypeScript class called KnoraResource, which can represent an instance of any project-specific Knora resource class. Here, though, I think it would be worth generating parts of this class. For example, every Knora resource has things like an ARK URL, a last modification date, and so on, and this metadata gets extended as new features get added to Knora. We could generate a TypeScript base class containing this metadata, and there could be a handwritten subclass that would handle Knora resource properties. The same goes for Knora value classes: there is some metadata that all value classes share, and these could be in a generated base class.

The Knora-ui core module also has TypeScript representations of Knora API v2 objects.

I think all these libraries should be combined into one. It doesn’t make sense to have three different TypeScript libraries for Knora.

@kilchenmann @flavie.laurens @t.schweizer @andreas @lrosenth @subotic

1 Like

PR 1259 (Generate client API code, part 1) has been merged. Once I get some feedback on the generated code, I can open a new PR to make any necessary changes.

A design discussion is starting here: https://github.com/dhlab-basel/knora-api-js-lib/issues/5