Project

General

Profile

API

Issue: #1050 Feel free to add and comment

To make it easier for other application to use data from OpenAtlas directly we plan to implement an API (application programming interface).

There are already some use cases:

  • OpenAtlas presentation software, developed by Stefan Eichert
  • ARCHE (for long time archiving), developed by ACDH

Great Resources on API development:

  • O'Reilly:RESTful Web APIs - deposited with Alex
  • OpenAPI - a machine readable API documentation format/standard, with a large ecosystem of tools built around it
  • JSON:API - a conceptual framework for API development and documentation
  • RF2616 - the HTTP specification, quite technical/theoretical, but good to be familiar with at least

Main purpose is the automatic data exchange between systems via URLs. At the moment we are in the concept phase.

  • All API request will include "api" after the domain URL e.g. demo.openatlas.eu/api/1234 for one entity or demo.openatlas.eu/api/actors for a list of entities
  • There will be multiple formats available (e.g. RDFS, JSON, XML)
  • First step is to get basic information of an entity via including the entity id in the URL
  • Next step will be to get (most) associated information e.g. information about super and sub entities, related entities like actors, events, ...
  • Finally it should be possible to get all the information needed for e.g. OpenAtlas frontend presentation software, either especially developed or with a generic parameterized URL solution

Since the API should be very stable (additions are ok but no interface changes for possible other systems already using it) we will take some time to plan it in detail.

To discuss:

  • How do we add CIDOC CRM related information and will this information be optional?
  • Do we allow the API to be accessed anonymously only after the data is already open or do we want a protected service. If yes, how can we secure it?
    • there are multiple levels of access restriction, some on protocol level (such as CORS), some on content level (such as AUTH requirements)
    • generally it should be considered if the API should provide CRUD functionality or be read only
  • Time format and especially for dates BC in GeoJSON-T https://github.com/kgeographer/geojson-t and https://www.loc.gov/standards/datetime/edtf.html
  • check names with Rainer Simon

Discussion outcome:

  • URL schema: /api/v2/entity/1234 or /api/v2/entity/1234.json for specific format
  • Output format: json as default, rdfs, ttl
    • strongly recommend using HTTP headers for content negotiation --> RFC2616)
  • Content: What to show in output - linked places, linked traces, cidoc mapping included, various options
  • Linked Places Format (LPF) provides a quite solid format and will be used
  • Stefan and Bernhard will meet up to create a first draft
  • The database structure is ideal for creating unique IDs. Rainer and Christoph approved of the doability, that every entity will be avaible with the URL shema /api/v1/1234
  • The CIDOC shema could be included with the tag "relations", but further research is requiered.

Preliminary JSON-LD:

{
  "type": "FeatureCollection",
  "@context": "https://thanados.openatlas.eu/api/v01/50505",
  "features": [
    {
      "@id": "https://thanados.openatlas.eu/place/view/50505",
      "type": "Feature",
      "properties": {
        "title": "Thunau Obere Holzwiese" 
      },
      "geometry": {
        "type": "GeometryCollection",
        "geometries": [
          {
            "type": "Point",
            "coordinates": [
              15.643286705017092,
              48.586735522177
            ],
            "classification": "centerpoint",
            "description": "Point in the center of the cemetery",
            "title": "Thunau centerpoint" 
          }
        ]
      },
      "when": {
        "timespans": [
          {
            "start": {
              "earliest": "750-01-01",
              "latest": "799-12-31" 
            },
            "end": {
              "earliest": "900-01-01",
              "latest": "949-12-31" 
            }
          }
        ]
      },
      "names": [
        {
          "toponym": "Thunau Obere Holzwiese" 
        }
      ],
      "types": [
        {
          "identifier": "https://thanados.openatlas.eu/api/v01/22378",
          "label": "inhumation cemetery" 
        }
      ],
      "links": [
        {
          "type": "closeMatch",
          "identifier": "https://www.geonames.org/2763660" 
        }
      ],
      "relations": [
        {
          "relationType": "crm:P2_has_type",
          "relationTo": "https://thanados.openatlas.eu/api/v01/5099",
          "label": "Excavation" 
        },
        {
          "relationType": "crm:P67i_is_referred_to_by",
          "relationTo": "https://thanados.openatlas.eu/api/v01/112759",
          "label": "Nowotny 2018" 
        },
        {
          "relationType": "crm:P67i_is_referred_to_by",
          "relationTo": "https://thanados.openatlas.eu/api/v01/116289",
          "label": "https://doi.org/10.2307/j.ctv8xnfjn" 
        },
        {
          "relationType": "crm:P46_is_composed_of",
          "relationTo": "https://thanados.openatlas.eu/api/v01/58775",
          "label": "Grave 001" 
        }
      ],
      "descriptions": [
        { "@id": "https://thanados.openatlas.eu/api/v01/50505",
          "value": "...In the area of Obere Holzwiese 215 inhumation burials were documented in different excavations. There might have been a wooden church in the north-western part of the areal, which might date back to the first half of the 9th century..." 
        }
      ],
      "depictions": [
        { "@id": "https://thanados.openatlas.eu/display/112760.png",
          "title": "Map of the cemetery",
          "license": "cc:by-nc-nd/4.0/",
          "@context": "https://thanados.openatlas.eu/api/v01/112760" 
        }
      ]
    }
  ]
}

Also available in: PDF HTML TXT