The entire Epigraf application is an Application Programming Interface (API). Epigraf allows data retrieval and modification by external programs via defined endpoints. In principle, Epigraf can also be used as a backend for independently hosted front ends. Data can be exchanged in a structured format (JSON). Further, rendered HTML components, such as the article list (without the layout), can be embedded in a front end via API access.

The endpoints correspond to the URLs that are visible when navigating the pages in the browser. To output structured formats via these endpoints instead of HTML web pages, append the desired format extension to the path:

• The XML format includes all content on a page and is structured hierarchically. For example, article elements contain all sections. XML is also a valuable starting point for export pipelines.
• The JSON format has a hierarchical structure, but is generally more compact than XML and easier to process for other applications.
• The CSV format contains tabular data and is compatible with many statistical programs. Epigraf outputs entities from different hierarchical levels (e.g. articles and their sections) in rows below each other. The hierarchy of entities is stored in id columns.

You will find buttons for different formats at the bottom of the pages. Alternatively, the URL displayed in the browser can be modified so that the path ends with the file format (.xml, .json, .csv).

Example: The article list of a database can be accessed in the browser via /epi/public/articles as a webpage.

• The same list can be retrieved in JSON format via /epi/public/articles.json.
• The data is served in XML format via /epi/public/articles.xml.
• A CSV table is generated via /epi/public/articles.csv.

Table pages such as the projects table or the articles table are served in a Hydra-compatible format, enabling harvesting of collections. If the appropriate configuration is set up, articles can be output in RDF-compatible triple formats.

• JSON-LD (jsonld extension)
• Turtle (ttl extension)
• RDF/XML (rdf extension)

In addition to retrieving structured data, the following rendered views can be generated:

• HTML (without extension): Interactive webpage to be displayed in browsers. To embedd components into another webpage, the show parameter can be used to select specific elements. The theme parameter determines the CSS styling.
• Markdown (md extension): Presentation of article content in rendered markdown.

All endpoints return UTF-8 encoded data. Non-printing characters such as the unit separator control character are filtered out.

Access to endpoints

An access token is required to access non-public data and for write access. This token is appended to the URL or sent as a bearer token, for example: /epi/stage/articles.csv?token=ABCDEFG. The token is generated in Epigraf's user account.

To use the access token, API permissions must be granted both for accessing the relevant database and for accessing the endpoint. For example, to use the articles/index endpoint with a token, the following permissions are required:

• User: \<username>
• Role: remains empty
• Requested by: "api"
• Permission type = "access"
• Entity Type: "databank"
• Entity name: \
• Entity ID: can remain empty, optionally the ID of the databank
• Permission name = "epi/articles/index"

General parameters of all endpoints

Common parameters

In all endpoints, the path parameter <db> must be replaced by the selected project database, for example by "public".

For index and view endpoints, the optional idents query parameter determines how IDs are composed in the ID fields:

• id: By default, the IDs are generated from the table name and entity ID, for example articles-551.
• tmp: Temporary IDs are created. When used in subsequent imports, new entities will be created for temporary IDs. Example: articles-tmp551.
• iri: Replace IDs by IRI paths, for example articles/epi-article/dresden~551.

Pagination and order

Each query returns as many entities as requested in the limit parameter. Additional entities can be retrieved using the page parameter.

Some endpoints support cursor-based pagination. With cursor-based pagination, a reference entity is defined as a reference point for the result. Cursor-based pagination can be used to narrow down a category tree (epi/<db>/properties/index) to specific segments. The seek parameter can be used to jump to specific nodes within the result list. For the properties/index endpoint, the entity hierarchy is expanded: ancestors of the filtered entities are always included in the result. In addition, when seeking a specific entity, the previous entities in the result set are returned.

Fields, columns and blocks

The index endpoints support selecting columns to be returned by using the columns parameter. Multiple columns are selected as a comma-separated list.

• If the columns parameter is empty, the default fields will be returned.
• Additional columns are configured in the types configuration by the columns key.
• Registered users can also request ad hoc columns using extraction keys. An ad hoc column consists of the caption, followed by an equal sign and the extraction key. The parameter must be URL-encoded because it contains an equal sign.

The extraction key can adress simple fields of the article object (e.g. title) or nested fields using dot notation (e.g. project.shortname). This follows the conventions of the types configuration. To access lists, an asterisk placeholder can be used (e.g. items.{\*}.value). Lists can be filtered with conditions in square brackets (e.g. items.{\*}[itemtype=conditions].date). For further details, see the CakePHP documentation on hash syntax.

By default, all ID fields contain IRI paths. To request IDs, use the idents parameter.

For HTML output, specific components can be explicitly requested using the show parameter. This allows, for example, the main content to be embedded in external pages without sidebars. The parameter supports a comma-separated list of the following elements:

• mainmenu: The main menu.
• searchbar: The search bar in table views.
• content: The main content area.
• footer: The footer area.
• leftsidebar: The left sidebar.
• rightsidebar: The right sidebar.

Styling of the rendered view depends on the theme parameter. The minimal theme creates a compact view with reduced outer margins, which is particularly useful when embedding content in iframes.

The flow parameter determines the click target of entities in a collection (e.g. table views). The options include frame, popup or tab.

Available endpoints

All endpoints are structured according to the same pattern. There are two different endpoint routes:

• Global endpoints access application level actions. They consist of a controller, which usually corresponds to a database table, the action to be executed and, if necessary, additional parameters: /<controller>/<action>?<parameter>
• Project endpoints additionally contain the path segment epi and a database name: <db>:/epi/<db>/<controller>/<action>?<parameter>

To find out the available endpoints, simply browse Epigraf in a webbrowser and pay attention to the adress bar. Each URL is an endpoint, consisting of a controller path (e.g. projects, articles, properties) and an action path. Typically, a controller provides the following actions

• index
• view
• show
• edit
• add
• delete
• import
• transfer
• mutate

List of endpoints

Note: The following documentation is not complete yet. But most endpoints can be inferred from the URLs in the browser address bar.

Projects

GET /epi/\<db>/projects/index

A list of all projects. Example: /epi/public/projects?term=greifswald.

Articles

GET /epi/\<db>/articles/index

A paginated list of articles. Identical to the short form GET /epi/<db>/articles.

POST /epi/\<db>/articles/import

Import articles including all associated data. The data structure must correspond to the Relational Article Model. Three variants are supported: 1. Provide a file to be uploaded and imported. 2. Provide the name of a file available on the server. 3. Provide JSON data.

Example: /epi/epi_movies/articles/import?filename=newmovies.csv

DELETE /epi/\<db>/articles/delete/

Delete an article, including its sections, items, footnotes and links.

Sections

POST /epi/\<db>/sections/move/\<id>

Move sections within an article after or before a reference section.

Properties

GET /epi/\<db>/properties/\<propertytype>/index

List of categories of a category type.

GET /epi/\<db>/properties/merge

A GET request results in a preview of how the target category would look after merging with source categories.

The endpoint can be used with query or with path parameters. Example: GET /epi/<db>/properties/merge/<source>/<target>.

POST /epi/\<db>/properties/merge

Merges multiple categories by transferring the contents of one or more source categories to a target category. If the concat parameter is set to '1', contents from text fields is merged. All references to the source categories (e.g. from articles) are rewired to the target category. The source categories are then deleted.

Example: POST /epi/public/properties/merge?source=2,3,4&target=1

The endpoint can alternatively be used with path parameters: POST /epi/<db>/properties/merge/<source>/<target>

If the tree structure is affected by the merge, a follow-up POST request should be executed on the endpoint /epi/<db>/properties/mutate/<propertytype> to recover the tree by a sort operation on the lft field.

POST /epi/\<db>/properties/mutate/\<propertytype>

The mutate endpoint can be used to perform batch processing tasks.

For categories, the sort task can be used to reorder the category tree. It is further used to recover the tree structure in case it gets invalid. Tree structures are invalid if the lft/rght values are no longer correct, for example after import processes or after merging categories.

Types

GET /epi/\<db>/types/\<scope>/index

The types endpoint returns the database configuration. Each type defines what kind of projects, articles, sections, items, annotations (links and footnotes) and categories occur in a database.