[Feature]: [FRSM-11] Does the software use open APIs that support machine-readable interface definition?

[karacolada]

D5.2 p19+p28

Detailed Description

An open Application Programming Interface can be freely accessed by other software or developers, which makes it easier to integrate software and encourages modularity and reuse.

Domain-agnostic comments

Only applicable if APIs are implemented.

The OpenAPI specification is a machine-readable interface definition language for describing, producing, consuming and visualising web services. Additionally, the SmartAPI project has developed a openAPI-based specification for defining the key API metadata elements and value sets, to maximise the FAIRness of web-based APIs.

This could be extended to test that the API is callable and does not return an error code.

CESSDA comments

Expectations around the API definition and documentation are set out in the section on CMA1.3 Development Documentation of the CESSDA Technical Guidelines. The section on CMA7 Demonstrate Usability notes that at SML5 (excellent standard) compliance with open or internationally recognised standards for the software and software development process, is evident and documented, and verified through testing of all components. At present, this is not being included in the assessment criteria as it is hard to automatically test, but could be independently verified through regular testing and certification from an independent group.

An extensible service enables additional services to be built on or around it, including adapting to changing functional requirements over time. This is done by making the integration point the API. New and/or existing services can be combined as required via their APIs to meet changing functional requirements. Versioning the APIs and supporting two versions simultaneously allows services to evolve, without breaking the contract they provide to their consumers (see docs).

Context

I1: Software reads, writes and exchanges data in a way that meets domain-relevant community standards.

Possible Implementation

domain-agnostic

requirements	Software source code, Software application
method	Call the software API.
essential	The software provides documented APIs
important	The APIs are open (freely accessible)
useful	The APIs include a machine-readable interface definition

CESSDA

requirements	Software application
method	Call the API
essential	The API meets SML3 of the CESSDA Development Documentation guidelines: there is external documentation that describes all API functionality, which is sufficient to be used by any developer.
important	The software’s REST APIs comply with the OpenAPI standard.
useful	The software’s REST APIs are described in the published CESSDA API definitions.

[karacolada]

Skeleton evaluator:

fuji/fuji_server/evaluators/fair_evaluator_api.py

Line 10 in 1778e73

class FAIREvaluatorAPI(FAIREvaluator):