What are the "interfaces" for Readium-2?

[rkwright]

There is much "agreement" that Readium-2 should have well-defined interfaces (APIs). What are those interfaces to? From? This clearly comes back to what is the overall architecture of Readium-2?
What language are they written in? JavaScript? TypeScript? IDL?

[HadrienGardeur]

It depends what you mean by interface, but IMO there's already something similar to the Readium-1 division being discussed:

• one part of the code will actually parse the EPUB by transforming the OPF into a JSON document and decrypting/streaming resources in HTTP
• this same part of the code could also expose a number of services, including a MO resolver (single document where all the info about MO are re-serialized in a more convenient way), a search service, a locator resolver etc.
• another part of the code will request these JSON documents, map them to an object stored in memory and make HTTP requests to display everything in a webview

Which means that we could have at least the following interfaces:

• HTTP itself is IMO an interface, with specific features based on what the server will support and which HTTP version we'll be using
• the manifest
• MO resolver document
• search result document
• locator resolver document
• etc.

[HadrienGardeur]

As a follow-up to our call and my previous comment: I think the HTTP server itself and the EPUB parser is a big building block here.

It can be:

• written in any number of languages, even on the same platform, without an impact for the rendering part
• used completely separately from the rendering (for example in other projects like FolioReader)
• either local or on the Web

Different modules can then plug into this building block. Let's take search for example:

• the search endpoint will be exposed in the manifest (links with the rel set to 'search') using a well-known URI template
• once the HTTP server receives a search request, it'll pass that request to the search module
• the search module will return a list of locators to the HTTP server
• the server will reply with a JSON document that contains these locators

I should be able to potentially replace the search module (for example use something Lucene based instead of a basic search), without any impact on what I've described above.

This provides a first idea of what the API and requirements could be for a number of modules. This includes:

• search
• navigation (TOC and other lists in the navigation document)
• media overlay resolver
• locator resolver

Other modules will either be entirely native or written in JS, this includes: pagination, user settings (style, night mode), notes/highlights/bookmarks, text to speech and media overlay support.

[HadrienGardeur]

For modules that won't be handled in HTTP through the manifest document, we could do the following:

• document the expected behaviour of the module in a Markdown document on this repo
• if a module has multiple implementation in a given language (for example pagination), we should also provide a list of method stubs that will be used by each implementation (method name, input, output)
• implementations should also share how they use fragment identifiers or query parameters (for instance all pagination modules could point to the last page if the URI contains "#readium-page-last")

For JS, I'm sure that other people who are more experts than I am could chime in cc @fchasen @danielweck @jccr