Biodiversity Information Science and Standards : Conference Abstract
PDF
Conference Abstract
A Case Study of Publishing Internal APIs to External Users
expand article info Max Patiiuk ‡
‡ Specify Collections Consortium, Lawrence, Kansas, United States of America
Corresponding author: Max Patiiuk (max@specifysoftware.org)
Received: 16 Sep 2021 | Published: 17 Sep 2021
© 2021 Max Patiiuk
This is an open access article distributed under the terms of the Creative Commons Attribution License (CC BY 4.0), which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited.
Citation: Patiiuk M (2021) A Case Study of Publishing Internal APIs to External Users. Biodiversity Information Science and Standards 5: e75386. https://doi.org/10.3897/biss.5.75386
 Open Access

Abstract

External service integration and adherence to industry standards has become ever more important for collections data management platforms. External APIs (Application Programming Interfaces), allow for the development of bi-directional data flows critical to service integration. In contrast to service-oriented backend APIs, public APIs must have continually up-to-date, comprehensive documentation that covers common use cases, on-the-fly request validation, and meaningful error messages. OpenAPI (OpenAPI Initiative 2021), a machine-readable API documentation specification can help significantly with testing and maintenance, and libraries can be used to automate common maintenance tasks.

Specify 7 is a biological collections data management platform developed by the Specify Collections Consortium (Specify Software Consortium 2021). This presentation summarizes the challenges and lessons learned with publishing the existing backend Specify 7 API to a public-facing external API. Each Specify 7 API is composed of 200 resources. A standard set of CRUD (Create, Read, Update, Delete) operations is provided for each resource for client interaction with a group of service-based endpoints for bulk operations such as file uploads, file-based data imports, and attachment manipulation.

To support the migration, we developed a custom library to enhance request validation. Parameter validation is extended through a real-time comparison against the existing schema and data. The library is available to the community under a MIT license on GitHub (https://github.com/specify/open_api_tools/).

In this presentation, we will close with an overview of the next steps for the Specify 7 public API. These include:

  • An update to the latest OpenAPI specification, version 3.1. The latest version aims to increase compatibility with the Javascript Object Notation (JSON) Schema specification, and thus would allow us to use JSON Schema (IETF Trust 2021) validation frameworks.

  • An in-depth evaluation of GraphQL for its ability to force all endpoints to be strongly typed and automatic validation of request parameters and response objects.

Keywords

OpenAPI, Specify Software, Specify 7, collections management system, API standards, biodiversity informatics, digital ppecimen architecture, databases, network integration

Presenting author

Max Patiiuk

Presented at

TDWG 2021

Hosting institution

Specify Collections Consortium

References

login to comment