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. for one entity or 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:

  • URL schema as a whole
  • Which output formats to offer (e.g. RDFS, JSON, XML) and how to request them.
    E.g. making one default and add a postfix like /api/1234 and /api/1234.json or prefixing them like /api/rdfs/1234 and /api/json/1234
    • strongly recommend using HTTP headers for content negotiation --> RFC2616
  • 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