Status: Draft


The purpose of this page is to document the wide array of existing API specifications, standards, and best practices that form the basis of the NCMNS API response bodies and structural design. Grouped by type and labeled accordingly, see the lists below. In many cases, a specific block of a response body can be attributed to a specification or API. The 'Response Body Relationships' section contains the latest list of these relationships. Creating an inventory of these relationships is a high-priority for the project and an ongoing process. The final section 'Extended Resources' contains a collection of important web-based resources specifically related to standardized responses and vocabularies in Web APIs.


Standards and Specifications

[1] OGC API Standards
[2] [3] Hydra (Hypermedia-Driven Web APIs)
[4] HAL - Hypertext Application Language [4] JSON-LD
[6] Data Catalog Vocabulary (DCAT) - Version 2
[7] WADG0001 WebAPI type extension
[8] Dataset API Discovery 0.3
[9] Bioschemas
[10] OpenAPI
[11] Datacite Metadata

Existing APIs

Name Link
Socrata Open Data API
NASA Planetary Data System API
Catalog of Life API

Best Practices

Name Link
OGC Web API Guidelines
Microsoft API Best Practices


Fielding, R.T., Taylor, R.N. (2002) Principled design of the modern Web architecture. ACM Transactions on Internet Technology, 2(2) 115–150. doi: 10.1145/514183.514185.
Wilkinson, M. D. et al. (2016) The FAIR Guiding Principles for scientific data management and stewardship. Scientific Data 3:160018 doi: 10.1038/sdata.2016.18.
Wieczorek, J., Bloom, D., Guralnick, R., Blum, S., Doring, M., Giovanni, R., Robertson, T., Vieglais, D. (2012) Darwin Core: An Evolving Community-Developed Biodiversity Data Standard. PLoS ONE 7(1): e29715. doi:10.1371/journal.pone.0029715.
Moudry, V., Devillers, R. (2020) Quality and usability challenges of global marine biodiversity databases: An example for marine mammal data. Ecological Informatics 56, 101051.
Feng, X., et al. (2021) : A review of the heterogeneous landscape of biodiversity databases: opportunities and 4 challenges for a synthesized biodiversity knowledge base. EcoEvoRxiv, 29 June 2021. Web.
Heberling, J.M., Miller, J.T., Noesgaard, D., Weingart, S.B., Schigel, D. (2020) Data integration enables global biodiversity synthesis. PNAS 118 (6) e2018093118;
Zobolas, J., Toure', V., Kuiper, M., Vercrutsse, S. (2021) UniBioDicts: Unified access to Biological Dictionaries. Bioinformatics 37(1), 143-144. doi: 10.1093/bioinformatics/btaa1065
Fielding, R.T. (2000) Architectural Styles and the Design of Network-based Software Architectures. Doctoral Dissertation, University of California, Irvine.


Lauret, Arnaud. The Design of Web APIs. United States, Manning, 2019.
Geewax, JJ. API Design Patterns. United States, Manning, 2021.
Hausenblas, Michael, et al. Linked Data: Structured Data on the Web. United States, Manning, 2014.
Richardson, Leonard, et al. RESTful Web APIs: Services for a Changing World. United States, O'Reilly Media, 2013.
REST: Advanced Research Topics and Practical Applications. Netherlands, Springer New York, 2013.
Masse, Mark. REST API Design Rulebook. Germany, O'Reilly Media, 2011.
Yu, Liyang. A Developer’s Guide to the Semantic Web. Germany, Springer Berlin Heidelberg, 2014.
Subramanian, Harihara, and Raj, Pethuru. Hands-On RESTful API Design Patterns and Best Practices: Design, Develop, and Deploy Highly Adaptable, Scalable, and Secure RESTful Web APIs. United Kingdom, Packt Publishing, 2019.

Response Body Relationships

Location Path References
Response Body metadata.links [1,5]
Response errors[] [1,2,5]
Response Body metadata.provider [2,4]

Extended Resources

Name Description
Standards.REST Collection of REST API standards and specifications
OpenAPI Specification v3.1.0 The defacto standard for API documentation
Public APIs Collections of Public APIs within a Scientific Scope
Public REST APIs Another Collection of Public APIs