DX, API Design & Documentation

Discussing the significance of API standardization


This article discusses the significance of API standardization.


A huge benefit of APIs in an ecosystem is standardization. When you look at multi-party ecosystems or ecosystems where multiple parties engage with each other, data providers, and data recipients, such as financial services, telecom, etc., you have a unique problem space you’re dealing with. For example, as a consumer, when you walk into a bank, Bank of America, Wells Fargo, or Chase, your experiences are somewhat similar. It is done purposefully because it creates a consistent consumer experience. If a consumer had different experiences, every time they went to a different bank, it would be confusing to the consumers and a nightmare for the regulators and the policymakers.

When you look at the APIs developed in ecosystems that are not based on standards, application developers have to deal with a nightmare. One bank decided they’re not going to send out statements; another bank decided they only make 30 days’ worth of data available; all very well-informed decisions in their silos but arbitrary decisions when you look at it as an ecosystem as a whole.


Industry Led Standardization is Powerful

Consider a space with 14,000 financial institutions and 11,000 FinTechs. You’re talking about millions of point-to-point connections that suffer from these inconsistencies. Standardization in such a space would allow a forum to build once without reinventing the wheel. So if you’re creating an API, you don’t need to worry about what an account type is and what should I call checking. You can use the terminology, and if you’re a data recipient, you can build once and reuse your implementation multiple times. It makes the resulting solutions secure and perfect, and you can ensure that you’re meeting your user experience goals versus spending all your money on solving the integration challenges.


Tech vs. policy in API Standardization

As we look at standardization, another question is the role of policy versus tech. If you’re examining what it means to standardize in your ecosystem, often, you may have inertia waiting for the government or the policymakers to do something. However, in our experience, relevant are best suited to defining policy outcomes they want, e.g., the speed on the highway should be 55 miles an hour. Now how that’s delivered is left to the car makers. So, governance does not ensure standardization.


Dimensions of API Standardization

Standardization is a mix of technical specifications and technology governance.


Technical Specifications


You have multiple organizations involved in the entire ecosystem. You want to have a consistent way of calling things, and that’s where things generally start.

User Experience

Then you define the user experience goals, who the users are, whether they’re human or non-human users, their roles in the ecosystem, and the use cases.


Based on that, you can start to define the data model and API interaction methodologies.


Once you have the data model that specifies the different types of data and knows who the users are, you can define the security profiles; you want to protect the sensitive data or keep delegates out of certain data types.

These are good aspects of standardization.


Technology Governance

Non-functional attributes

But if you want to drive adoption and through great standards have wide adoption, you want to make sure you’re addressing the governance aspects, the non-functional attributes, and the APIs are there. For example, if somebody has a developer portal but can’t access it, or if it’s down 50% of the time, that API is less than useful.

Reference Implementation

Have a reference implementation for the newcomers coming into the ecosystem to know what they should do, what comes first, and what comes second.


The more mature ecosystems also have a certification program to assess the entities on the quality of their implementation.


And then finally, a registry that collects information on all the participants and describes their capabilities so anyone participating in the ecosystem can figure out who to work with, discover their capabilities, and shorten their implementation cycle.


Real-life Example

Let us look at a real-life example of how financial data exchange (FDX) capitalized open banking in the US. Consider an international nonprofit standard-setting body dedicated to unifying the financial industry around a secure, interoperable, and royalty-free standard. That standard solves the problem of secure access to permission data for consumers and small businesses. It is a very broad-based organization with 206 members and growing. Two-thirds of the members are not banks. However, the governing structure is balanced between the FIS and non-FIS to ensure the standards are being created with equal weighting to all parts of the ecosystem.

Further, the voting mechanism and the community-based development process ensure that small firms have as much of a voice as big firms. Some of the best ideas come from the FinTechs, and we want to ensure they are not drowned out by the compliance and risk people in the big organizations. It is deliberately set up to support innovation and progress.

All standards bodies are generally successful if they focus on a specific problem. And FDX is no different. The specific problem that FDX was set up to solve was the need for consumers to share their credentials with third parties to access the data.

We spend a lot of time designing these beautiful websites. But almost half the time, those websites are being used by bots who don’t care about the screen’s color or the user workflow that you’ve built up; they’re all interested in scraping the data off and pushing it into the app.


FDX Approach to financial data sharing

We started with the taxonomy. We created a definition of the different roles and the actors within the system and the interactions that happen. Data recipients are entities that receive data; they don’t have to be FinTechs. Similarly, data providers don’t have to be financial institutions. Data access platforms make it easy for data providers to communicate with several data recipients and vice versa. At the heart of it is the end user that permissions the data from the provider to the recipient.


We then invested time in establishing five core principles based on which the standards are created – Control, Access, Transparency, Traceability, and Security; CATTS for short.

Control implies the end user should be able to permission their financial data in the financial app of their choice; they are in control.

Access means the user should have access to the financial data and also be able to determine which entities can access data on their behalf.

They should have transparency into how, when, and for what purpose the data is being requested and that the requested data conforms to the original intent of the request; you’re not pulling in more data than you need for your business purpose.

All data transfers should be traceable, and the user should have visibility into all parties involved in the data-sharing chain.

And finally, entities should ensure the data as it transits from one entity to another is kept secure and ensure privacy is maintained.


We then proceeded to create the user experience guidelines. They describe how the user experience controls access to financial data, starting with the principle of consent grant. Consent originates at the point of need, which is the application that needs the data. It represents what data it needs and for what purpose. That consent then moves on to the data provided. The user has perfect visibility on both sides, and once they authorize, that action is called a consent grant. Once consent is granted, all the related parties are notified that some data will be shared on this account. They can manage their consent on the banking dashboards.


In terms of API and data standardization, FDX has taken a two-fold approach to standardization. So here’s the second part of the standardization, which is the certification use cases. Data profiles are defined for specific use cases such as personal finance, lending, account thinking, payments, etc. So if that’s what you want to do, then as a provider, you know that you want to implement these 200 elements or these 20 elements for this use case. And somebody can ask you for that specific use case and know that they’re going to be able to work with your implementation.


A big part of the standards development is ensuring we are tracking other standards. We reference TLS, OIDC, and OAuth2. In some cases, we’ve taken existing standards and developed our profiles, for example, IETF’s dynamic client registration protocol. We created a profile on top of that specific to our ecosystem.


On the standard side, there is also a need to inform and educate as the regulators move ahead with policymaking. We do not advocate. We don’t pick winners and losers. We leave that to the policymakers to set policy objectives, but we want to ensure the policies are informed by technology and what’s happening in the industry.


At this point, we’ve gone from 2 million consumer accounts in the spring of 2019 to 32 million consumer accounts in two and a half years. In adopting the UX guidelines, you would notice on your banking sites as well that banks are starting to show controls for the end users to manage consent and the applications that the access has been granted to. For consumer permission data sharing, an increasing number of publicly announced and many more non-public data sharing agreements are out in the market.


In summary, our lead standards have a successful track record. The secret to success is inclusivity and a thoughtful approach to standardization.


Dinesh Katyal
I am a strategic thinker with great execution skills, who learns quickly and loves to create great products and awesome product teams. I use a customer backed approach, with qual/ quant methodologies to create compelling product value propositions. I deliver with quality and passion using principles of Agile development balancing short term wins with long term goals. I love building teams, hiring great talent, mentoring them for success and taking satisfaction in seeing team members grow their careers. I've had full stack experiences delivering on enterprise software with eBay, HP, VeriFone, Tacit and Euclid, as well with consumer applications with Intuit, and Xero. I have spent the most time in product management in payments, fintech, eCommerce, risk, platforms, open banking and accounting. However, I'm naturally curious and love to expand my horizons. I would love to hear from you, so please do not hesitate to reach out.

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture