API Structure

Status: Draft

Overview

The NCMNS API is tightly organized into a hierarchical structure using a specific classification terminology. The primary goals of the structure is to facilitate reuse, provide context and meaning to resources, and improve usability and discoverability. Given the exponential usage and opportunities provided by APIs, a mechanism that allows resources to be grouped by function or context greatly improves usability and ease of use. The NCMNS API structure consists of the following three tiers: Class > Type > Name.

  1. Resource Class. At the highest level of the API hierarchy, resources are grouped based on function and purpose to enhance discoverability and ease of use.
  2. Resource Type. Context/subject matter is the basis for resource groups within a resource class.
  3. Resource Names. A unique name (with a GUID) assigned to each resource, the foundational building blocks of the API.

Resource Classes

  1. Data Products - A collection of data published and curated by a single data provider and represented as static, bulk resources [1]
  2. Services - Endpoints that perform a specific function and return dynamically generated responses based on the request
  3. Vocabularies - Sets of terms with definitions for the purpose of describing and interpreting data.
    Diagram: https://data.naturalsciences.org/diagrams/resource-classes

Resource Types

Class: Data Products

  1. Checklists - Hierarchical catalogs of recognized taxa within a taxonomic group.
  2. Ecological Traits - Collections of heritable features measurable at the individual level for a species or higher taxonomic group.
  3. Geography - Catalogs of physical or geopolitical features formatted with non-spatial data types.

Class: Services

  1. General - Service-based endpoints with customized response bodies that support internal and external applications, services, and workflows.
  2. Spatial - Service that contains information formatted as one or more spatial data types in the request, response, or both.

Class: Vocabularies

  1. Data Dictionaries - Comprehensive linked terms and descriptions that describe response body parameters in endpoints belonging to the NCMNS API.

Diagram: https://data.naturalsciences.org/diagrams/resource-types

References

[1] Data Catalog Vocabulary (DCAT) - Version 2 (https://www.w3.org/TR/vocab-dcat/)[https://www.w3.org/TR/vocab-dcat/#]