Opencast API

Agenda

• Lessons learned
  • What's wrong with the APIs
    • Metadata JSON format hard to work with since it's very compley and you have to iterate over lots of data
    • Inflexible upload of formats
    • Pagination is hard (it's an array, no oibject and has no total, …)
    • Changing the API is very dificult
    • Deprecation policy is missing
    • Complexity of the code (many layers)
    • Code internally connected to other parts of Opencast (hardly stable)
    • No guarantee that operation has actually happened (ActiveMQ async handling)
    • Run multiple instances of the external API (loadbalancing & resiliance)
  • What's good about the API
    • SUDO is nice
    • Self describing API (partly)
    • Farcade is nice
• Alpha/Beta API endpoints
  • Definitely start with unstable API
  • Group parts of API
    • e.g. make events API and user API independent
    • discussion about where to draw the line needs to happen eventually
    • having a version for each and every endpoint does not make sense
    • there may be another solution is using GraphQL but we talk about that later
• Authentication/Authorization
  • We want some kind of token auth so that external applications can talk to Opencast without users having to provide a plain text password
  • Will have an OAuth webinar in the next couple of weeks
  • As a user:
    • You want to give a tool access
    • You don't want to give the tool your credentials
    • you want to be anle to revoke access
      • access can expire
  • Different "permissions"/Scopes. The application can request different permission from the user, the user has to agree to those and the permissions are associated with the token. The token cannot be used for anything that hasn't been explicitly requested in the beginning.
• Deprecation
  • Proposal on list
  • Maybe if we have an alpha version, it cannot stay aplha forever but needs to be evolved or dropped
• Versioning
  • Increase version for breaking changes only
• Merging some APIs
  • Maybe admin and external
• Capture Agent API
  • Would maybe be one group
  • API format (REST, GraphQL, …)
• Going forward