API design

[LukasKalbertodt]

Our GraphQL API grew very organically over the past years, basically only driven by our specific frontend needs. And that is fine, as the API is internal and we don't promise any stability. But maybe it's time to clean it up a bit, looking at it from an API design standpoint, not purely driven by the day-to-day requirement.

We are getting more and more questions about whether people can use the API, which we always have to decline. We already have a semi-stable part of the API. namely the part that is used by the Admin UI integration. We might want to properly stabilize parts of our API for everyone at some point and having a good API design is required for that. Further, a good design just makes it easier to work with it for our day to day tasks.

This issue is not something I expect we tackle very soon, but I wanted to have a place to collect ideas already.

---

Some random ideas I had:

• Single endpoint to get some object with different parameters

  • Currently we have realmById and realmByPath; eventById and eventByOpencastId, ...
  • Maybe we can replace all of them with realm, event, series and playlist endpoints
  • All these endpoints would have multiple optional parameters that allow the user to choose how to look up the item, e.g. realm(id: ID, path: String). Then users can call realm(id:"abc") or realm(path:"/foo").
    • Sadly, the "only specify one of those arguments" cannot be enforced by the GraphQL type system as far as I can tell. But I don't think that would lead to any actual bugs in production, I would think this kind of error would immediately get noticed in development.
  • For the Opencast items, we could also add a hybrid: String parameter (name tbd) that accepts exactly our route syntax of <tobira-id> or :<oc_id>. That would drastically reduce some routing frontend code, getting rid of 6 route definitions. This seems a bit "adhoc" and driven by a very specific frontend need, but we cannot change route URLs anymore anyway, so that hybrid-ID syntax is now part of Tobira. So I don't think it's too bad to also put it into the API.

• Maybe improve return type of event and playlist. It's currently a union either AuthorizedFoo or NotAllowed. And null can also be returned. This bothers me: the series endpoint is different; the main type for event/playlist is called AuthorizedFoo; every query requires this annoying ...on AuthorizedEvent { .. } level of indirection; we have to have this fake type NotAllowed with a dummy field.

  • We can of course just rename AuthorizedFoo to Foo and the Foo to FooResult or something else.
  • But can we maybe find another way of modelling this? So yes we have to model two special case: item not found and access not allowed.

• Adding consistency to the series/event "state" handling. We tried to avoid getting involved with sync-state stuff, but now it's too late and Tobira has to deal with it. Might as well have a consistent API for this.

• Generally consistencies. Go through the whole API and see if there are any points where the same problem is solved in different ways.

• ...

(Ole feel free to just add ideas)