Project

General

Profile

Actions

Api » History » Revision 25

« Previous | Revision 25/86 (diff) | Next »
Bernhard Koschicek, 2020-01-17 12:36


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

Resources

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
  • FastAPI - an interesting project to create a fast API
  • LinkedTraces - Maybe for actors'?
  • JSON-LD-Playground useful tool

Purpose

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.

Discussions

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
  • Should we add class to the json output? (e.g. E40, E18)

Discussion for 27.11

  • For places we use the type "FeatureCollection", how should we name the other entities?
  • Should we also use "feature": [] for other entities also? The thing is, that every information is in feature, but an actor doesn't have a "feature". Or do we say, it is ok "feature":[] includes any entity
  • Should we differentiate between E18 and E53? Alex and Bernhard would say no
  • Should we use commet at "when": {"timespans":[]}? Is is technically no problem and an additional information some could need
  • We have to thing about, how long we want to maintain old API versions and how we implement a version system
  • What should happen, if a Type/Node is requested from the API? Should we show the parent and all subtypes? Or only show parent?
  • What should happen with empty tags?
    • e.g. an entity doesn't have dates, is the "when":{} tag empty or not present?
    • e.g. an entity has no types.. etc.
  • Should @context reference to the api Uri? The linked places documentation states: "In JSON-LD, labels for object elements are aliases for terms formally defined in linked ontologies. For Linked Places, those mappings are listed in this context document.(http://linkedpasts.org/assets/linkedplaces-context.jsonld)"

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
  • 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.

JSON Templates

Feature Collection

Preliminary JSON-LD:

{
  "type": "FeatureCollection",
  "@context": "https://raw.githubusercontent.com/LinkedPasts/linked-places/master/linkedplaces-context-v1.jsonld",
  "features": [
    {
      "@id": "https://thanados.openatlas.eu/entity/50505",
      "type": "Feature",
      "crm-class": "E18",
      "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",
              "comment": "" 
            },
            "end": {
              "earliest": "900-01-01",
              "latest": "949-12-31",
              "comment": "" 
            }
          }
        ]
      },
      "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" 
        }
      ]
    }
  ]
}

Actor

Preliminary JSON-LD:

{
  "type": "Actor",
  "@context": "https://raw.githubusercontent.com/LinkedPasts/linked-places/master/linkedplaces-context-v1.jsonld",
  "features": [
    {
      "@id": "https://thanados.openatlas.eu/entity/11920",
      "type": "Legal Person",
      "crm-class": "E40",
      "properties": {
        "title": "Abbey Schliersee" 
      },
      "when": {
        "timespans": [
          {
            "start": {
              "earliest": "779-01-21",
              "latest": "779-01-21",
              "comment": "Datation of charter" 
            },
            "end": {
              "earliest": "1803-01-01",
              "latest": "1803-12-31",
              "comment": "Secularisation in Bavaria" 
            }
          }
        ]
      },
      "names": [
        {
          "alias": "Schliersee" 
        },
        {
          "alias": "Schliersee Abby" 
        }
      ],
      "relations": [
        {
          "relationType": "crm:P107_has_current_or_former_member",
          "relationTo": "https://thanados.openatlas.eu/api/v01/155",
          "label": "Freising, Bishopric" 
        },
        {
          "relationType": "crm:P67i_is_referred_to_by",
          "relationTo": "https://thanados.openatlas.eu/api/v01/2120",
          "label": "Jahn 1991" 
        },
        {
          "relationType": "crm:P67i_is_referred_to_by",
          "relationTo": "https://thanados.openatlas.eu/api/v01/117",
          "label": "Trad. Freising" 
        },
        {
          "relationType": "crm:P67i_is_referred_to_by",
          "relationTo": "https://thanados.openatlas.eu/api/v01/11923",
          "label": "TF 94 Foundation of Schliersee by Adalunc and his brothers" 
        },
        {
          "relationType": "crm:P22i_transferred_title_to",
          "relationTo": "https://thanados.openatlas.eu/api/v01/18524",
          "label": "Arbeo consecrates the church in Schliersee" 
        }
        {
          "relationType": "crm:P74_has_residence",
          "relationTo": "https://thanados.openatlas.eu/api/v01/11926",
          "label": "Abbey Schliersee" 
        }
      ],
      "descriptions": [
        { "@id": "https://thanados.openatlas.eu/api/v01/11920",
          "value": "In the year 779 Adalunc and his brothers Hiltipalt, Kerpalt, Anton and Otakir established the monastery of Schliersee. They build the church with the consent of bishop Arbeo who also consecrated the church.
The noble man Perhtcoz was elected as abbot and they lived under benedictinian rule." 
        }
      ],

      "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" 
        }
      ]
    }
  ]
}

ToDo

  • Write a new function to get all links (every direction)

Updated by Bernhard Koschicek about 1 month ago · 25 revisions

Also available in: PDF HTML TXT