Which problems can tooling fix - and with which tools?

[Kevsy]

This list suggests four areas in which tooling can simplify and accelerate development of CAMARA-compliant APIs.

Once the list has been discussed/agreed we can map the items to tools, some of which are already in use. Some tools can be hosted on GitHub workflows, some may be better on local IDEs (Visual Studio extensions etc.)

Please make suggestions in the comments below. Any feedback from the Spring 25 meta-release assessment will be welcome, so we can aim to help with the Fall 25 reviews.

Development

• use of latest info templates from Commonalities & ICM
• use of latest schema items from Commonalities artefacts
• correct whitespace indent
• no trailing whitespace

Validation

• API definition follows syntax rules of CAMARA API Design Guidelines
• API definition follows terminology rules of CAMARA API Design Guidelines
• filename syntax follows CAMARA API Design Guidelines
• proofreading (typos, grammar)
• identifying changes that are non-backward-compatible

Security

• YAML definition passes checks against OWASP Top 10 API Security threats
• user-created input values do not allow SQL injection/buffer overflow/XSS

Testing

• Test definitions follow CAMARA API Design Guidelines
• Test definitions account for scenarios covered in User Story
• Test definitions account for errors declared in API definition
• contract testing (related to the non-backward-compatible point above)

Release Management

• correct release number with correct syntax
• correct version and URL
• valid Changelog
• API Readiness Checklist updated and mandatory items confirmed
• post-release: prepare PR that resets API version in YAML to wip after each release - can be run manually by codeowners

[rartych]

Small automation for the recurrent task:

• prepare PR that resets API version in YAML to wip after each release - can be run manually by codeowners

https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/14557919/API+versioning#API-version-types

A work in progress (wip) API version has the following information in the API OAS definition file:

Info object - version: wip (instead of x.y.z)
Servers object - url: vwip (instead of vx)

A wip API version may exist in 2 cases

during the first introduction of a new API upto the creation of the first alpha API version
during the time that one or more Pull Requests (PRs) are committed after a given release of an API.

[Kevsy]

Thanks, added to list above including link to this comment.

[rartych]

@Kevsy are you familiar with EditorConfig? I've just heard about it.

The .editorconfig file (reflecting .md .yaml and .feature formating rules) can be prepared in tooling and added to repository template.
This would help when using local editors (it seems the Gihub WebEditor supports EditorConfig in very limited way) to avoid linting errors like trailing spaces, indentation,etc.

[Kevsy]

@rartych I only spotted it in VS Code, but yes great that it can apply across editors to apply consistent indents and removal of trailing whitespace.

And: if this is applied to the Commonalities YAML artefacts as well, then it will make it easier to either import or copy-and-paste common YAML into API specifications without causing an indent issue.