The difference between resources, endpoints, objects, and items in the bunq API documentation
As a developer, you must have browsed dozens of API documentation websites and noticed that nomenclature might differ from one site to another. In our docs and blog articles, we use our own version of common API terminology that is mostly universal but still might be confusing or unknown to some of our readers.
In this article, we are going to clarify our understanding and use of some terms we frequently use. So, what’s the difference between a bunq API resource, object, item, and collection? Let’s find out!
Resources
Architecturally, resources are data sets that an API allows you to work with, and which are accessible via endpoints. They have relationships with other resources as well as a set of (allowed) operations that you can carry out on them.
On the level of documentation, resources are presented as sets of endpoints grouped on the basis of related data or the object they allow working with. Resources have simple names that are easy to comprehend, which makes it easy for users to find the right endpoints but may lead to overlooking essential functionality.
Resources do not serve as umbrella units for related endpoints, even though it may seem so from browsing API documentation. For example, invoices are possible to read and list via the endpoints from the invoice resource, but you need to use the endpoints listed under the pdf-content resource to export an invoice.
At the same time, one resource can sometimes be accessed from “different angles”. For instance, you can list all invoices linked to a user, or you can choose to do the same for a monetary account. Given that the user has only one monetary account, you get the same information via alternative endpoints.
Objects
Objects are backend instances with properties, wrappers around related data that, in most cases but not always, represent resources. That is why “objects” and “resources” are often used synonymically.
Objects help by working with resources. Here is a couple of examples:
Example 1: You use objects in the request and response bodies. If you want to close the status of a savings monetary account, you set the status field of the MonetaryAccountSavings object CANCELLED in the request body. If you list monetary accounts of a user, they will be wrapped into objects in the response body too.
Example 2: Objects can (internally) assist not being linked to a resource. Creating a scheduled payment creates an internal Schedule object that we manipulate but don’t store in our database. It just helps us carry out the function needed.
Endpoints
Endpoints are URIs that embody the location of the resource that you want to do a CRUDL operation on.
The relation between a resource, an endpoint, and an HTTP method is the following: What → Where → Action
Collections
Collections are simply groups of resources. You’ll find that we don’t mention any collections in the API documentation. That is because we offer singleton resources, which are independent and exist outside of any collections.
Although we occasionally mention our Postman collection, it is not a part of our API design. It is a set of basic API calls that help you get started with the bunq API via Postman. The cherry on top 🍒 is that it contains both the sandbox and production environments, so switching between them is just a matter of two clicks.
Items
When browsing the API reference, you’ll find ItemIds among the required parameters. They are nothing more complicated than just IDs of the object in question.
For example, the endpoints of the user-company and user-person resources will contain the itemId parameter. In this case, you need to pass the userID of the user type object.
The other way round, userID = itemId of the UserCompany / UserPerson object.
Using the knowledge in practice
We use our own API for the bunq app non-stop. We think in the terminology mentioned above, and so it makes sense to us.
How was it for you to deal with the terms we use in our API-related content?
Haven’t experienced the freedom of programmable banking yet? Make your first sandbox payment in seconds! No need to create API keys. ;)
Choose your language:
$ bash >(curl -s https://tinker.bunq.com/php/setup.sh)
$ bash >(curl -s https://tinker.bunq.com/python/setup.sh)
$ bash >(curl -s https://tinker.bunq.com/java/setup.sh)
$ bash >(curl -s https://tinker.bunq.com/csharp/setup.sh)
