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:
- THANADOS OpenAtlas presentation software, developed by Stefan Eichert
- ARCHE (for long time archiving), developed by ACDH-CH
Main purpose is the automatic data exchange between systems via URLs.
- All API request will include "api" after the domain URL e.g. demo.openatlas.eu/api/0.1/1234 for one entity or demo.openatlas.eu/api/0.1/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.
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
- http://www.geojsonlint.com/ -> Test if valid GeoJSON
This is a overview how the API can be requested:
- Request one entity: /api/0.1/entity/105 or /api/0.1?entity=105
- Request multiple entities: /api/0.1?entity=105&entity=111
- Request by code: /api/0.1/code/actor
- Request by class: /api/0.1/class/E18
- Request by latest: /api/0.1/latest/16 (int = number of entries)
- Password or token based authentication?
- The Linked Places field names (https://github.com/LinkedPasts/linked-places#names-required) requires at least one citation of the toponym name. Is it really required for our purpous? We can't provide a Gazetter link or citation so it is not reasonable.
- Depictions Licences, how to get the cc: namespace? We will make something like, if the string contains "cc" followed by "by" then add cc: in front of the name.
- What shape type should we give an entity without real geometry? I would give it "Point" just out of simplicity
- Is it really necessary for each project that we will give valid geojson? e.g. actor has geometry. Should we include more json shemas?
- Add Exception handler
- Research for correct implementation of mimetype
- Add authentication/endpoint login for API
- Maybe implement everything with Flask-RESTful-API https://flask-restful.readthedocs.io/en/latest/index.html