New API

[LukasKalbertodt]

With the data model changing quite significantly in some ways, there is the obvious question of how to expose that to the world. Opencast currently has a number of APIs (external API, search API, ...). We talked about this on 2025-07-31.

We decided already:

• We want a new API!
  • Advantage: this clearly communicates that the data model has changed. Reusing and adjusting the old API runs the risk of lots of small breaking changes going unnoticed.
  • Additionally: new API allows for a fresh clean start without baggage. It allows us to switch to some other API framework if we so wish.
  • Of course, not all old APIs are deleted. Some are important to keep around, like ingest and CA APIs.
  • We also said that a single OC release will: introduce new data model, new API and remove old API. We might want to support (via updates) the previous version for longer.
• We want to listen to feedback for the API more and adjust over time until we're happy to stabilize.
• The API should be "self-describing":
  • Meaning, the API has well typed responses and parameters. GraphQL has this out of the box: you always know exactly what the response JSON looks like. We don't need to use GraphQL, but we want this property. JSON-Schema is a potential alternative. For example, would be great to generate Typescript bindings for the API automatically to type check frontend code. Also: it would be great if the API explorer UI lets you look at the exact response type as well.
• We want to experiment with different API frameworks (OpenAPI, GraphQL) to see what works well. See Experiment with new API for new data model (OpenAPI with dummy data) opencast#6968

Open questions

• What "framework" do we use? OpenAPI, GraphQL, ...?
  • To decide this, we need to experiment: Experiment with new API for new data model (OpenAPI with dummy data) opencast#6968
• How does the API look like exactly?
• What APIs do we want to combine? E.g. merge all functionality of the search API into "the one new API"? Are there problems with the micro-architecture of it all? "Read only mode" is relevant here maybe.

Previous discussions:

• 2025-07-31
• Discuss: remaining topics #3 (comment)

[mtneug]

What "framework" do we use? OpenAPI, GraphQL, ...?

OpenAPI = REST? That would be the question for me. Basically RESTful vs GraphQL. While I quite like grpc, I don't think Opencast devs would want that. I don't have a strong opinion and only slightly prefer continuing with REST as this is already known in the community.

How does the API look like exactly?

There have been some talks / docs for what we want from a new API. Notes are a bit scattered. At this point, I would suggest working on a document that defines the API, i.e. what endpoints are there and how does the data look like. From there we can iterate.

What APIs do we want to combine? E.g. merge all functionality of the search API into "the one new API"? Are there problems with the micro-architecture of it all? "Read only mode" is relevant here maybe.

To arrive at some answer to this, here is how I would group the current APIs:

APIs for other services

• /admin-ng (Admin UI)
• /editor (Editor)
• /studio-api (Studio)
• /lti* | /lti-service | /lti-service-gui (LTI)
• /tobira (Tobira)
• /ui/config (public config files)

External API

• /api

Capture Agent API

• /capture-admin
• /recordings

Ingest API

• /ingest

OAI-PMH

• /oaipmhinfo

Search API

• /search

Misc

• /info
• /metrics
• /play
• /redirect
• /sysinfo
• /termination

Service APIs

• /assets (special case as this is useful for accessing archived assets)
• /staticfiles (special case for uploading random static files (used for themes); maybe this could be removed in the future)
• any other endpoint

IMO what this issue should focus on is a nice API facade for primary external use. Currently, I think that would mean combining the External API and the Search API.