Backend API

• • Introduction
  • Authentication
  • Storage
    • XWiki API
    • GitHub API
    • NextCloud API
    • File API
  • Rendering (server side rendering)
  • LiveData

Introduction

This is a draft of the backend API which should be supported for each backend. A JS API will be defined which Cristal will interact with and the possible implementation on the server side will be indicated for each type of backend (XWiki, NextCloud, GitHub, LocalDrive).

The APIs in this document are an early draft.

Authentication

Authentication is a complex problem and needs to be studied. Multiple authentication methods should be possible:

• Providing a username/password and authenticating on the backend and receive a cookie or a token
• Open a Window to follow an authentication flow and generate either a cookie or a token
• Follow up requests should be succesful using the cookie or a token to insert the credentials in each HTTP request

• backend.authentication.getConfig
• backend.authentication.auth
• backend.authentication.authUsingAuthenticationFlow (not sure it's needed)
• backend.authentication.refreshAuth
• backend.authentication.forgetAuth
• backend.authentication.verifyAuth
• backend.authentication.addCredentialsToRequest(httprequest)
• backend.askForCredentials (if custom credentials UI)

Associated Wiki 3.0 api

• wiki30.askForCredentials

TODO: verify that this API would support SSO OIDC authentication using XWiki.

Storage

• (JSON-LD) backend.storage.getDocument(reference)
  • document has a syntaxID
• backend.storage.saveDocument(reference, JSON-LD)
• backend.storage.exists(reference)
• backend.storage.getAttachment(reference)
• backend.storage.saveAttachment(reference)
• backend.storage.getComments(reference)
• backend.storage.addComment(reference)
• backend.storage.updateComment(reference)
• backend.storage.renameDocument(reference, newtitle, newreference)
• backend.storage.copyDocument(reference, newtitle, newreference)
• backend.storage.query (similar to xwiki query API with multiple APIs)
• backend.storage.getPageNamingStrategy(reference)
• backend.storage.convertReference(reference, pageNamingStrategy)

TODO: check APIs needed for create screen

TODO: study more page naming strategy

XWiki API

TODO

GitHub API

• config (storage strategy, filename escaping rules)
• convert reference to directories (using storage strategy)
  • each directory needs to be safe from a directory name pov
  • filename needs to be safe from a directory pov
• save file as JSON-LD using GitHub API

NextCloud API

• config (storage strategy, filename escaping rules)
• convert reference to directories (using storage strategy)
  • each directory needs to be safe from a directory name pov
  • filename needs to be safe from a directory pov
• save file as JSON-LD using WebDAV

File API

TODO

• config (storage strategy, filename escaping rules)
• convert reference to directories (using storage strategy)
  • each directory needs to be safe from a directory name pov
  • filename needs to be safe from a directory pov
• save file as JSON-LD on disk

Rendering (server side rendering)

• backend.storage.renderDocument
• backend.storage.renderMacro

LiveData

TODO: based on LiveData API