OpenAtlas API¶

• Table of contents
• OpenAtlas API
• Versioning
• Error handling
• Output format
• Endpoints
• OpenAtlas backend
• Parameters
• Cross-Origin Resource Sharing
• Related OpenAtlas API links
• Resources

OpenAtlas provides an API which is RESTlike to easily access data entered in OpenAtlas.
A complete overview of possible endpoints and usage is available at our swagger documentation.

Versioning¶

The OpenAtlas API tries to follow REST principles, but OpenAtlas provides multiple versions of the API

• Deprecated version (currently API 0.2)
• Stable version (currently API 0.3)
  • No breaking changes will be made, but new features and additions may be added
  • Deprecation of endpoints and parameters will be marked for next versions

Error handling¶

The OpenAtlas API provides two layers of errors catching.

• First layer: validates a given parameter of an endpoint. Errors are caught by the Flask-RESTful extension, which has its own error handler.
• Second layer: is a self build error model, for details see: API Error Handling

Output format¶

Please see API Output Formats for specifications.

• LinkedPlacesFormat (LPF) with extensions for OpenAtlas (standard)
• A simpler GeoJSON format
• RDF (derived from LPF, maybe incomplete)
  • XML
  • Pretty-XML
  • Turtle
  • Notion 3
  • N-Triples

Endpoints¶

Overview of available endpoints: Endpoints
The API can be accessed via the following schema: {domain}/api/{api version}/{endpoint} for example: demo.openatlas.eu/api/0.3/entity/1234

OpenAtlas backend¶

If advanced layout is selected in your profile, a link to the different formats of entities is shown on their specific page.
If the option Public is activated in site settings (default is off) the API can be used even when not logged in.

Parameters¶

Overview of all parameters used in different versions: Parameters
Endpoints can take in multiple parameters entered after the URL e.g.: demo-openatlas.eu/api/code/actor?sort=desc&limit=300

The first parameter has to have a ? to mark the parameter sections begin. More parameters can be added with &.

api/code/actor?sort=desc&limit=300

Cross-Origin Resource Sharing¶

Please visit CORS for more information.

Related OpenAtlas API links¶

• API 02
• API 03
• API 04
• API Authentication
• API Error Handling
• API Output Formats
  • GeoJSON Format
  • Linked Places Format
  • Thanados Format
• CORS
• Endpoints
• Parameters

Resources¶

general 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
• https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Versioning

• http://static.googleusercontent.com/media/research.google.com/en//pubs/archive/32713.pdf
• https://stackoverflow.com/a/398564
• https://www.mnot.net/blog/2012/12/04/api-evolution
• https://restfulapi.net/versioning/
• https://www.developer.com/web-services/best-practices-restful-api/
• https://nordicapis.com/everything-you-need-to-know-about-api-versioning/
• https://www.thecodebuzz.com/restful-api-versioning-best-practices/
• https://www.freecodecamp.org/news/how-to-version-a-rest-api/
• https://apisyouwonthate.com/blog/api-versioning-has-no-right-way
  • https://datatracker.ietf.org/doc/html/rfc8594
• https://github.com/dclucas/web-api-changes-catalog
• https://medium.com/@diogo.lucas/api-design-fundamentals-usage-driven-design-f1beffceae87
• https://livebook.manning.com/book/the-design-of-everyday-apis/chapter-9/v-11/18
• https://medium.com/@andreasreiser94/why-hateoas-is-useless-and-what-that-means-for-rest-a65194471bc8
• https://cloud.google.com/blog/products/api-management/understanding-grpc-openapi-and-rest-and-when-to-use-them
• https://nordicapis.com/designing-a-true-rest-state-machine/
• https://nordicapis.com/when-is-an-api-truly-rest-vs-rest-like/