Introduction

api
Since version 7.0 of TEI Publisher, nearly all requests to the server are handled via an API (the only exception being requests for static resources like images or CSS styles). The entire API is expressed in a formal specification based on the Open API standard. Within TEI Publisher you can browse the API by opening the Documentation/TEI Publisher API page from the menubar. Here you’ll see a list of URL paths (or API endpoints as we often call them).

Organization of the API

api
As can be seen on the API documentation page, the different endpoints are grouped into categories (“tags”) like documents, collection, odd etc. This grouping is just for your convenience and has no technical implications. You’ll also find that there is a separate section at the bottom, called Custom API. This is specifically for endpoints you want to add on top of TEI Publisher’s default endpoints. We’ll use this below. More important is another distinction: looking at the endpoint paths we see two kinds: those starting with /api and those without prefix, which all appear under the view tag.

Adding an Endpoint to Browse Places

api
Assume you have an edition in which all references to places are tagged. The references point to a central authority file containing further information on each place. In the simplest case this might be a separate TEI document with the list of places contained in /TEI/standoff/listPlace. An example (taken from the Alfred Escher Briefedition) is attached below. TEI Source places.xml (1420 kb) As an alternative entry point into the edition, we may want to provide users a page on which they can browse through all place names and see their location on a map.

Combining Endpoint and Webcomponent

api
We now have the endpoint ready, so the next step is to actually create an HTML page and plug it in. First, check if you have the correct version of the tei-publisher-components library (> 1.32.0). Next, create a file below templates, e.g. templates/places.html and paste in the following HTML: <?xml version="1.0" encoding="UTF-8"?> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="width=device-width, minimum-scale=1, initial-scale=1, user-scalable=yes"/> <link rel="shortcut icon" type="image/x-icon" href="resources/images/favicon.ico"/> <link rel="shortcut icon" type="image/png" href="resources/images/favicon-16.

Registering a Different URL

api
Right now the user needs to navigate to places.html to get to our new page. For convenience, we may want to publish this page under a different URL, e.g. /tei-publisher/contexts/places. We could thus register another endpoint in our API definition to map /contexts/places to the places.html template. We can re-use an existing API function for this, so we don’t need to write any XQuery. The existing function is called vapi:html. Add the following endpoint definition to custom-api.

Showing Places on a Map

api
In addition to browsing through the places, it would also be nice to display their location on a map. Ideally the map should display all places occurring in the edition, so we can easily see which places are geographically close. We would thus need an additional endpoint, returning a simple list of all places with their geographical coordinates. Let’s add an endpoint for /places/all above our existing endpoint for /places: