Designing an API for a mineralogical database

An Application Programming Interface (API) is a secured, documented and accessible web service and an entry point to any database—both relational and non-relational. As a rule, it exposes the data in different formats and allows filtering of the data by utilizing the query parameters. Accordingly, it allows the developers and data scientists to retrieve and query data through HTTP or WebSocket protocols using command-line HTTP clients or language-specific ones (e.g., axios, requests). The most complicated and essential aspects of developing an API are choosing the stack, structuring the codebase and optimizing the application's performance. 

A general rule of thumb is to develop an API to be (1) platform-independent and (2) support the versioning and evolution of the service by adding new functionalities while supporting the previous versions. Other features of a robust and reliable API are documentation according to OpenAPI Specification (OAS), scalability, caching, development and production environments portability, concurrency and more.

mineralogy.rocks API for mineralogical and related data is currently a work in progress with open-source code. It follows RESTful architectural concepts, best practices of clean codebase development and the twelve-factor methodology. The application is developed in Django—a Python web framework and utilizes PostgreSQL 13 database under the hood. The APIs' design is organized around the resources, e.g. the endpoints' naming conventions are predictable, standard and follow the same patterns. 

The codebase structure deviates from the standard out-of-the-box structure provided by the Django framework to isolate database-, server- and application-specific utilities. The local environment of the application is set up using Docker and docker-compose containerization technology for the efficiency of the development. 

The CI/CD integration has zero downtime—it is organized around GitHub Actions that allow for building the application, deploying the isolated container to a cloud, and updating the Kubernetes cluster application accordingly. 

The mineralogy.rocks API supports open science and promotes the innovation, quality, and public impact of mineralogy. Our open science activities are implemented to make the results produced and used in research publicly available and their metadata quickly and widely available for reuse.

This project, No. 3007/01/01, has received funding from the European Union’s Horizon 2020 research and innovation Programme based on a grant agreement under the Marie Skłodowska-Curie scheme No. 945478 and was supported by the Slovak Research and Development Agency (contract APVV-19-0065).