Best Practices For Publishing Regulatory API Standards

Collaborative Development: Hosting the specification development on an open platform brings together developers, financial experts, and industry stakeholders in a collaborative way, where they can collectively contribute to the development and improvement of Open Banking API specifications. This open-source approach fosters innovation, rapid iteration, and wider adoption.

Transparency: Anyone can review the specifications, provide feedback, and suggest changes, promoting accountability and ensuring the standards are robust and well-vetted.

Version Control: As we move towards Open Finance and Open Data, maintaining and documenting changes becomes critical. A streamlined versioning of Open Banking specifications ensures backward compatibility and a smooth developer transition.

Community Engagement: Collaboration platforms typically provide community features such as issue tracking and pull requests, and facilitate discussions among contributors. This engagement can lead to quicker issue resolution, better problem-solving, and the incorporation of diverse perspectives into the specifications.

Accessible Documentation: Clear and comprehensive documentation is crucial for the successful implementation of Open Banking API specifications, and open collaboration platforms ensure easy access for developers and stakeholders via a user-friendly interface.

Integrations and reference implementations: In addition to thorough documentation, exemplary implementation of APIs, Swagger files, and reference code like SDKs is of tremendous help for developers and integrators, and supports smooth onboarding.

Many countries and authorities are already relying on open collaboration tools to develop national Open Banking standards. Oftentimes, platforms like Github, Confluence, Swaggerhub, or proprietary solutions are being used. There is, however, much diversity in the way these platforms work, which features are supported, to which degree they allow – and how they manage – community engagement.

Countries like the UK and Australia, for instance, maintain very thorough processes and make extensive use of community features via their Github project pages. They provide comprehensive documentation, be it as text, or as reference implementations or integrations. Collaboration with a wider community is happening, and there are clear versioning and regular updates.

Other countries like Brazil, Bahrain, and Malaysia are still ramping up their community engagement, and even though most of these already have Open Banking specifications published, there’s often only little participation from external stakeholders. Documentation is somewhat incomplete, and there are only a few code examples or reference implementations. In comparison, this makes onboarding much more difficult and cumbersome for Fintechs and developers.

Regulatory bodies who decide to build open banking API specifications by themselves could follow the following recommendations:

1. Use a clear and meaningful repository name. E.g. “Open Banking”, and “Official Open Banking UK API Standards” sound clear.
2. Organise Your Repository. Consider the following structure:
   1. Root Directory: This is where you can store high-level documentation files, such as a README.md that provides an introduction to the API and instructions on how to use the specification and the provided example implementations or reference code.
   2. Specifications Folder: Create a dedicated folder to store the actual API specification files. These might be in formats like OpenAPI (Swagger) YAML/JSON or RAML.
   3. Examples Folder: Include a folder with usage examples, which can help developers understand how to interact with the API endpoints.
   4. Contributions Folder: If you’re allowing external contributions, set up a folder where developers can submit proposed changes or additions.
3. Add Your API Specification. Place your API specification files, such as an OpenAPI YAML files, inside the “Specifications” folder. This file should detail the API endpoints, request and response formats, authentication methods, and any other relevant information. We suggest your endpoints use a clearly named root e.g. /yourcountryopenfinance/ so it can easily coexist with other standards on a server or development machine.
4. Write Clear Documentation. In the root directory of your repository, create a high-quality README.md file. This file should provide a concise overview of the API, its purpose, and how to use the provided specification. Include example API calls and responses to demonstrate real-world usage. Clear documentation ensures that anyone who visits your repository can quickly understand the API’s functionality.
5. Collaboration and Versioning. GitHub’s collaboration features shine when it comes to working on API specifications. Collaborators can review, suggest changes, and provide feedback through issues and pull requests. To manage different versions of your API specification, consider using Git tags or branching strategies. This helps keep track of changes over time while ensuring backward compatibility.
6. Regular Updates and Maintenance. APIs evolve over time, so it’s important to regularly update and maintain your specification. If you make changes to the API, update the specification and examples accordingly. Encourage your collaborators to provide feedback and report issues so that your API remains robust and accurate.
7. Integrations. Consider integrating tools like Swagger UI or ReDoc to visualise and interact with your API specification directly from your GitHub repository. These tools can enhance the user experience for developers exploring your API.
8. Test. Test if your specification is properly defined with Open API specifications (Swagger) since this is what developers will use to help implement your specification.
9. Copyright. Clearly mark your specification and documentation with copyright – or copyleft notices. By not stating any licence, the default copyright laws will apply, so if you want your specification to be used you should state a reasonable licence.

Setting up and running an open repository for your API specification can greatly enhance collaboration and understanding among developers, financial experts, and industry stakeholders. With a well-organised repository, clear documentation, and effective collaboration, you’ll be well on your way to creating a successful Open Banking/Open Finance program that meets the needs of your project.

For a guide on how to publish your repository reach out to contact@openbankproject.com