Level 61
Depends on what you want to build, and more importantly how you want to build it. What are the use cases and business rules?
Jul 13, 2021
5
Level 4
API design: returning a sub-set of data (with example)
Getting straight to the point - I use a banking app which allows me to send money to other people's accounts. The process involves entering their account number and sort code which is then checked and returns the account 'name' or the account holder's name which helps me confirm I have got the detail correct.
This is really useful since it makes me feel sure I'm sending money to the right account but it got me thinking about the process behind the account lookup.
If there was a publicly available API for such a process, how would it work?
Presumably there would be an endpoint to get an account having provided an account number and sort code in order to provide the account name to confirm the details. However, a GET request on an account item could also be expected to return a lot more information about an account, most of which may be private to the account owner.
So would there be a best practice to deal with this an maintain a RESTful design?
Solutions (and their caveats) that spring to mind are:
-
Create a separate endpoint to return only the account name for confirmation e.g.
/accounts/lookup/{id}. Does that break REST and if so, should I be bothered? This approach also means if the request ID was an incrementing number i.e./accounts/344users could guess and therefore get the names of all accounts if they wanted so the ID would probably need to be more obscure. I can imagine scenarios where users wouldn't want the existence of their accounts to be known. I guess the bottom line is you'd need to expose at least some information in order to receive any money at all. -
Check the permissions of the user making the request to a 'standard' endpoint (
/accounts/{id}) and if they are not the owner, only provide the data required to perform the action. Would this approach require sub-resources to handle the data being returned and would this also break REST since I understand endpoints should return a consistent data model.
I hope that makes sense.
Thanks.
Level 80
@chris_j It’s a query. You‘re submitting data to the server and want to get a response back based on the parameters you’ve provided. For this reason, I’d make it a POST request. Something like:
curl -X POST \
-d 'account_number=12345678&sort_code=123456' \
https://example.com/api/account-lookup
You’re also going to want to require authentication (and authorisation using permissions/scopes) for this endpoint, and rate-limit it. You don‘t want some nefarious user hammering your API and building up a database of account numbers and sort codes to names.
That being said, banking is a tightly regulated industry. There’s also the OpenBanking API specification for financial institutions who need to build and offer an API when dealing with bank accounts, but obviously that is tightly controlled too. You can’t just build and release an API because it’s highly sensitive data and if something goes wrong (wrongly expose financial data, something goes wrong transferring funds, etc) then you’re going to get sued to oblivion.
Level 4
@martinbean, thanks for the reply.
Luckily, personally, I'm not building something like this - my question was more based on the theory/design principles behind the requirement such as getting data that might not 'belong' to that user and what the implications are in terms of keeping such an API RESTful. There would always be some variation in this based on the scenario in question.
Clearly it would be a case of evaluating what data is available to users that don't 'own' the resources in question but of course your points on auth and rate-limiting are completely valid.
Level 54
if you are looking for an existing solution using open banking, then look at https://nordigen.com/en/products/account-information/
Level 4
Thanks, that's useful.
Please or to participate in this conversation.