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.
karacolada
commented
1 month ago
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
CESSDA