Application Server¶

The application server is built with Python and Flask.

The application server resides at ~capitularia/prj/capitularia/capitularia/server/. It is started as a systemd service by /etc/systemd/system/capitularia.service.

It is composed of these modules:

server¶

The main server module.

The API server for Capitularia.

build_parser(default_config_file)¶: Build the commandline parser.

data_server¶

Data API server for Capitularia.

REST Interface to perform various database queries.

Endpoints¶

GET /data/manuscripts.json/¶

Return all manuscripts.

Example request:

GET /data/manuscripts.json/?status=publish HTTP/1.1
Host: api.capitularia.uni-koeln.de

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "filename": "file:/var/www/.../cap/publ/mss/avranches-bm-145.xml",
    "ms_id": "avranches-bm-145",
    "title": "Avranches, Bibliothèque municipale, 145",
    "siglum": "Av"
  },
  {
    "filename": "file:/var/www/.../cap/publ/mss/bamberg-sb-can-12.xml",
    "ms_id": "bamberg-sb-can-12",
    "title": "Bamberg, Staatsbibliothek, Can. 12"
    "siglum": "Ba",
  },
  {
    "filename": "file:/var/www/.../cap/publ/mss/barcelona-aca-ripoll-40.xml",
    "ms_id": "barcelona-aca-ripoll-40",
    "title": "Barcelona, Arxiu de la Corona d'Aragó, Ripoll 40"
    "siglum": "Bc",
  }
]

Query Parameters:

status (string) – Optional. ‘private’ or ‘publish’. Default ‘publish’. Consider all manuscripts or just the published ones.
siglum (string) – Optional. Return only manuscripts that have the given siglum. Note: sigla are not necessarily unique.

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – no error

GET /data/capitularies.json/¶

Return all capitularies that have a transcription.

Example request:

GET /data/capitularies.json/?status=private HTTP/1.1
Host: api.capitularia.uni-koeln.de

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "cap_id": "BK.138",
    "title": "Capitulare ecclesiasticum",
    "transcriptions": 17
  },
  {
    "cap_id": "BK.139",
    "title": "Capitula legibus addenda",
    "transcriptions": 29
  },
  {
    "cap_id": "BK.140",
    "title": "Capitula per se scribenda",
    "transcriptions": 24
  }
]

Query Parameters:

status (string) – Optional. ‘private’ or ‘publish’. Default ‘publish’. Consider all manuscripts or just the published ones.

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – no error

GET /data/capitulary/<cap_id>/chapters.json/¶

Return all chapters in capitulary cap_id.

Example request:

GET /data/capitulary/BK.168/chapters.json/ HTTP/1.1
Host: api.capitularia.uni-koeln.de

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "cap_id": "BK.168",
    "chapter": "1",
    "transcriptions": 7
  },
  {
    "cap_id": "BK.168",
    "chapter": "1_inscriptio",
    "transcriptions": 1
  },
  {
    "cap_id": "BK.168",
    "chapter": "2",
    "transcriptions": 8
  }
]

Query Parameters:

cap_id – The capitulary id, eg. ‘BK.123’ or ‘Mordek.4’
status (string) – Optional. ‘private’ or ‘publish’. Default ‘publish’. Consider all manuscripts or just the published ones.

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – no error
400 Bad Request – Bad Request

GET /data/capitulary/<cap_id>/manuscripts.json/¶

Return all manuscripts containing capitulary cap_id.

Example request:

GET /data/capitulary/BK.40/manuscripts.json/ HTTP/1.1
Host: api.capitularia.uni-koeln.de

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {"ms_id":"bk-textzeuge"},
  {"ms_id":"vatikan-bav-chigi-f-iv-75"}
]

Query Parameters:

cap_id – The capitulary id, eg. ‘BK.123’ or ‘Mordek.4’
status (string) – Optional. ‘private’ or ‘publish’. Default ‘publish’. Consider all manuscripts or just the published ones.

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – no error
400 Bad Request – Bad Request

GET /data/corresp/<corresp>/manuscripts.json/¶

Return all manuscripts containing corresp.

Example request:

GET /data/corresp/BK.40_1/manuscripts.json/ HTTP/1.1
Host: api.capitularia.uni-koeln.de

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "filename": "file:/var/www/.../cap/publ/mss/cava-dei-tirreni-bdb-4.xml",
    "locus": "cava-dei-tirreni-bdb-4-243v-1",
    "ms_id": "cava-dei-tirreni-bdb-4",
    "siglum": "C",
    "n": 1,
    "title": "Cava de' Tirreni, Biblioteca Statale del Monumento Nazionale Badia di Cava, 4",
    "type": "original"
  },
  {
    "filename": "file:/var/www/.../cap/publ/mss/ivrea-bc-xxxiv.xml",
    "locus": "ivrea-bc-xxxiv-53v-8",
    "ms_id": "ivrea-bc-xxxiv",
    "siglum": "I1",
    "n": 1,
    "title": "Ivrea, Biblioteca Capitolare, XXXIV",
    "type": "original"
  },
  {
    "filename": "file:/var/www/.../cap/publ/mss/vatikan-bav-chigi-f-iv-75.xml",
    "locus": "vatikan-bav-chigi-f-iv-75-94r-6",
    "ms_id": "vatikan-bav-chigi-f-iv-75",
    "siglum": "V5",
    "n": 1,
    "title": "Vatikan, Biblioteca Apostolica Vaticana, Chigi F. IV. 75",
    "type": "original"
  }
]

Query Parameters:

corresp (string) – The @corresp, eg. ‘BK.123_4’
status (string) – Optional. ‘private’ or ‘publish’. Default ‘publish’. Consider all manuscripts or just the published ones.

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – no error
400 Bad Request – Bad Request

GET /data/capitulary/<cap_id>/chapter/<chapter>/manuscripts.json/¶

Return all manuscripts containing chapter.

Example request:

GET /data/capitulary/BK.40/chapter/1/manuscripts.json/ HTTP/1.1
Host: api.capitularia.uni-koeln.de

Query Parameters:

cap_id (string) – The capitulary id, eg. ‘BK.123’ or ‘Mordek.4’
chapter (string) – The chapter, eg. ‘1’ or ‘1_inscriptio’
status (string) – Optional. ‘private’ or ‘publish’. Default ‘publish’. Consider all manuscripts or just the published ones.

Response format see above.

GET /data/query_manuscript_parts.json/¶

Return all manuscript parts that satisfy a set of conditions.

This endpoint can be use to query convert attributes like date range or place of origin into a list of eligible manuscript parts. The solr_server can then be queried restricted to those manuscript parts.

Query Parameters:

status (string) – Optional. Return all or only published msparts, must be either ‘publish’ or ‘private’, defaults to ‘publish’.
notbefore (integer) – Optional. The mspart must not be older than this year
notafter (integer) – Optional. The mspart must not be younger than this year
places (list[string]) – Optional. List of places, the mspart must originate from one of these places

Example request:

GET /data/query_manuscript_parts.json/?notbefore=1100&places[]=ferrara&places[]=brixen HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {"ms_id":"modena-as-130","msp_part":""},
  {"ms_id":"paris-bn-lat-3878","msp_part":""},
  {"ms_id":"weimar-hsa-depositum-hardenberg-fragm-9","msp_part":""}
]

class DataBlueprint(name: str, import_name: str, static_folder: str | ~os.PathLike[str] | None = None, static_url_path: str | None = None, template_folder: str | ~os.PathLike[str] | None = None, url_prefix: str | None = None, subdomain: str | None = None, url_defaults: dict[str, ~typing.Any] | None = None, root_path: str | None = None, cli_group: str | None = <object object>)¶

capitularies()¶: Return all capitularies with transcriptions.

chapters(cap_id)¶: Return all chapters in capitulary cap_id.

fstat()¶: Create a filter on page status.

highlight(conn, text, fulltext)¶

Snippet and highlight

Produce snippets out of the text around any of the words in fulltext and highlight those words in the snippets.

manuscripts()¶: Return all manuscripts

places_json()¶: Return hierarchy of known places for the meta-search box.

query_manuscript_parts()¶: Returns a list of manuscript parts.

query_manuscripts()¶: Return manuscripts according to query.

stat()¶: Create a filter on page status.

collator_server¶

This module implements the collator API for the Capitularia Application Server.

Endpoints¶

POST /collator/collate¶

Collate sections of witnesses.

Example request:

POST /collator/collate HTTP/1.1
Host: api.capitularia.uni-koeln.de
Content-Type: application/json;charset=utf-8

{
    "collate": [
        "BK.20a_3/bk-textzeuge",
        "BK.20b_3/bk-textzeuge",
        "BK.20b_3/vatikan-bav-reg-lat-263[V10]"
        "BK.20b_3/vatikan-bav-reg-lat-263[V10]?hands=XYZ"
        "BK.20b_3/vatikan-bav-reg-lat-263[V10]?hands=XYZ#2"
    ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "witnesses": [
    "BK.20a_3/bk-textzeuge",
    "BK.20b_3/bk-textzeuge",
    "BK.20b_3/vatikan-bav-reg-lat-263[V10]"
  ],
  "table":[
    [ [ {"t": "A",     "n": "a" } ],     [ {"t": "A",      "n": "a" } ] ],
    [ [ {"t": "black", "n": "black" } ], [ {"t": "white",  "n": "white" } ] ],
    [ [ {"t": "cat",   "n": "cat" } ],   [ {"t": "kitten", "n": "kitten" } ] ]
  ]
}

Response Headers:

Content-Type – application/json;charset=utf-8

Status Codes:

200 OK – No errors.

class CollatorBlueprint(name: str, import_name: str, static_folder: str | ~os.PathLike[str] | None = None, static_url_path: str | None = None, template_folder: str | ~os.PathLike[str] | None = None, url_prefix: str | None = None, subdomain: str | None = None, url_defaults: dict[str, ~typing.Any] | None = None, root_path: str | None = None, cli_group: str | None = <object object>)¶

exception CollatorError(msg)¶

collate() → Response¶: Implements the /collator/collate endpoint.

normalize_with_patterns(patterns, text, whole_words=False)¶: Normalize text using a list of patterns

preprocess(text: str, normalizations: list[str] | None = None) → list[list[NGrams]]¶

Preprocess the input to the collator

Builds the representation for one witness. Returns an object that must be combined into the witnesses array.

Parameters:: normalizations (string[]) – List of string in the form: oldstring=newstring Normalizations applied to each word.
Returns:: The representation of one witness.

geo_server¶

Geo queries API server for Capitularia.

class GeoBlueprint(name: str, import_name: str, static_folder: str | ~os.PathLike[str] | None = None, static_url_path: str | None = None, template_folder: str | ~os.PathLike[str] | None = None, url_prefix: str | None = None, subdomain: str | None = None, url_defaults: dict[str, ~typing.Any] | None = None, root_path: str | None = None, cli_group: str | None = <object object>)¶

capitularies_csv()¶: Return capitularies in geometry as CSV response.

capitularies_json()¶: Return capitularies in geometry as geojson response.

extent_json()¶: Return the max. extent of all data points.

info_json()¶: Info endpoint: send information about server and available layers.

msparts_csv()¶: Return location of manuscript parts as CSV response.

msparts_json()¶: Return location of manuscript parts as geojson response.

mss_csv()¶: Return location of manuscripts as CSV response.

mss_json()¶: Return location of manuscripts as geojson response.

places_capitularies_json()¶: Return all places along with capitularies count.

places_msparts_json()¶: Return all places along with msp_part count.

places_mss_json()¶: Return all places along with mss count.

tile_server¶

A tile server for Capitularia.

This is a simple OpenStreetMap-style tile server using mapnik to render the tiles.

The probability of the client requesting adjacent tiles is very high. To speed things up, we ask mapnik to render a bigger “metatile”, which we cut into tiles and then cache the tiles. We also add some padding around the metatile, which helps avoiding ugly label placement when a label is near a metatile border.

info_json()¶: Info endpoint: send information about server and available layers.

class tileBlueprint(name: str, import_name: str, static_folder: str | ~os.PathLike[str] | None = None, static_url_path: str | None = None, template_folder: str | ~os.PathLike[str] | None = None, url_prefix: str | None = None, subdomain: str | None = None, url_defaults: dict[str, ~typing.Any] | None = None, root_path: str | None = None, cli_group: str | None = <object object>)¶

tile_png(mapid, zoom, xtile, ytile)¶: Tile endpoint: serve a tile as PNG.