DX, API Design & Documentation

Capital One API Best Design Practices


Ado Trakic is a part of the platform services Centre of Excellence team within Capital One. In this article, he discusses API design practices at Capital One and how these practices help the API-producing team succeed.

Capital One has come a long way in its digital transformation. We have undergone a data-driven digital transformation, effectively leveraging modern technologies, such as artificial intelligence and machine learning, for data insights that can help our customers better. We treat data as a product, and using the power of APIs, data delivery happens in real time for faster insights. We are not just a bank; we are using technology to change the banking industry. As we sometimes say, we are banking on technology. Capital One has become one of the world’s greatest software engineering companies. We have spent many years working to improve, create and upgrade software, and adopt the latest and greatest tech trends in software development and infrastructure.

There is a big focus on standardization and automation for software development and deployment so that developers are fully equipped to deliver very high value and ship high-quality software products much faster. Our products are preventing online fraud, empowering partners to innovate with us, and helping other businesses harness the power of the cloud.

APIs are the glue that holds the digital world together. We are trying hard to focus on usability, to have as polished API governance as possible, and to be able to realize API governments at scale. It helps collaboration with teams across the enterprise. We are pushing for an API-centric approach to software development. It is an ever-evolving journey.

The platform services Center of Excellence team is responsible for –

  • To accelerate transformation
  • Support development teams
  • Work on tooling and automation
  • Create creating standards and guidelines for the entire enterprise
  • Provide training
  • Adopt new technologies
  • Develop support tools
  • Facilitate compliance in a highly regulated industry.

We have a very sophisticated design review process with multiple steps. Using this process, we can achieve API governance at a large scale because we have thousands of APIs and many software development teams. The steps are as follows –

  1. Plan
  2. Design
  3. Review
  4. Develop
  5. Production

We look into APIs that come to us as a product in the review process. We ensure full compliance with any API delivered, emphasizing standards and practices.

APIs need to be discoverable. Always have a number of API patterns available for the teams that can be used as the building blocks for APIs. We get inputs from all teams when we set standards so that standards are not enforced, and it is a team effort.

The benefits of a well-designed API are –

It conveys a clear purpose and value

It is self-service and easy to use.

It increases communication and collaboration between API producers

It increases speed to market.

At the heart of this, we have a DevExchange platform. The platform has many components, like an API lifecycle tool, discovery portals, and a very sophisticated platinum-level gateway for real-time traffic for APIs.

Classification of APIs

APIs are classified as common and private APIs. Common APIs are the ones that can be used by multiple teams that have reusability aspects. They go through a full design review to ensure they follow all standards and practices. Private APIs are not published and have minimal integrations. They undergo a light-touch review.

API Consumption Models

  • Internal – accessible on an internal network
  • External – accessible externally
  • Partner – accessible to vetted partners

It is important to start practicing the design-first approach. So, we try to start API-first before any implementation effort starts.

Five guiding principles for APIs

  • Have a minimalist approach – Less is better – limiting requests to data in response to what’s necessary. Do not expose unnecessary data points.
  • Intuitive – Should be easy to learn, understand and use.
  • Nonproprietary – There is an emphasis on language use within the APIs with no abbreviations, jargon, references to systems, names, technologies, etc.
  • Usable – Design APIs for reuse across business groups.
  • Standard compliance – APIs should conform to HTTP Design standards, RESTful standards, and other API standards
Ado Trakic

Ado Trakic

Enterprise API Architect at Capital One
Excellent track record providing innovative information technology solutions to business clients and senior level consulting in both government sector and private industry. Extensive experience in helping various organizations undergo digital transformation efforts by providing program, project management, governance, systems implementation and integration support on multi-phase, multi-year projects. Expertise in making in enterprise wide technology and business decisions. Expertise in Cloud Computing, Enterprise Architecture, software engineering, SDLC, systems security, business process mapping, modeling and re-engineering efforts.

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