Why we have created the SCDS API Friendliness Checker
Designing good APIs is often a tough task. It can take quite some time to thoroughly think through all your endpoints and many other API features. But doing this from the start will probably save you countless headaches in the long run.
Having a good idea of what your API will look like is a great starting point to better understand how your product will work and how data will be distributed before even writing a single line of code. A transparent, logical structure also makes improvements easier that will inevitably come as an application or service evolves and grows.
And last but not least: A good quality API makes life easier for the developers you want to use your endpoints and data. Arguably, the exact point of APIs is for them to be accessible and usable by others. Hence, the friendliness of APIs, particularly for developers, is a key feature of any API.
That is why the Support Centre for Data Sharing has developed the API Friendliness Checker. It helps you to check your API against essential quality and usability criteria (as seen from a developer perspective) and provides comprehensive feedback on what should be improved. To assess your APIs friendliness, you can either enter a URL with your API description or paste the description to the online editor . The API description must always be in YAML-format. Once you press "Validate", the API Friendliness checker will evaluate your API and display any feedback on the right, next to the editor window.
Based on the OpenAPI description to facilitate API standardisation
The API Friendliness Checker builds on the OpenAPI Specification, an established and widely recognised standard for describing APIs adhering to REST criteria. The OpenAPI Specification was developed with accessibility in mind so that services and applications implementing it can be understood by humans and machines alike without access to the programming code or documentation. This is crucial when developing applications in the field of data sharing.
Note that not all the steps are necessary or even relevant for all types of data or all data sharing scenarios. While the example describes the appropriate steps for confidential and proprietary data, in case of other types of data (like open data or public personal data) some of the steps can be ignored while others (e.g. data storage) must always be present. Chances are that in most non-trivial data sharing scenarios, most of these steps are mandatory and, given their generic nature, can be considered as building blocks for a well-designed data-sharing preparation.
The rest of the section is dedicated to the detailed description of each data sharing building block.
API Friendliness Checker Assessment Criteria
We may over time amend assessment criteria as we learn and get feedback on which other characteristics are important to users. Version 1.0.0 of the API Friendliness Checker evaluates adherence to the following key criteria
- Use of the OpenAPI Specification
- Use of sematic versioning (SemVer)
- Correct naming of variables:
- snake_case instead of camelCase
- Enum values declared with UPPER_SNAKE_CASE
- Pluralising array and resource names
- Correct variable properties:
- Not using null for Boolean properties
- Using same semantics for null and absent properties
- Using date properties according to RFC 3339
- Using standardised property formats
- Using standardised country, language and currency codes
- Avoidance of trailing slashes in URLs
- Not using special characters in resource identifiers
- Resources and sub resources are identified in path segments
- Specification of success and error responses
- Use of standard HTTP status codes
- Make correct use of HTTP methods
- Support of partial responses via filtering
- Support of pagination