NBB RESTful API Design Guide

The RESTful API Design Guide of the National Bank is now free and open source. Check out this post to know more about it.


The National Bank of Belgium (NBB) has published its RESTful API design guide under the terms of the EUPL license.

That guide serves as the current standard for the creation of all current Web APIs within the bank. It is an important design document for us because it regroups all the choices that have been made and those serve as a set of rules for our development teams.

Why do we need a design guide for APIs?

Choices choices choices…

There are many ways to implement Web and/or RESTful APIs and, at this point in time, no clearly winning industry standard. There are many design choices to make: * high level design: pagination? filtering? search? sorting? … * detailed design: page=2? offset=10? version in the URL or in a header? …

When there are many options to choose from, development teams can argue forever about the best solution for each use case.

There are various standardization efforts that cover a lot of ground and multiple ways to formalize «REST» APIs (e.g., json-api, OData, OpenAPI, …) but none that catered for all aspects we wanted to cover in the APIs of the National Bank of Belgium.

Within larger environments, standardization is key for developers productivity, ease of integration between applications

While preparing for the development of our Web APIs, we’ve decided to create our own design guide, with our own choices, covering our current and known future needs.

What’s in the guide?

In our design guide you’ll find:

Where can I find it?

Right here: https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki