DX, API Design & Documentation

Supercharge digital democracy with API first approach


This article by Luke Lipan focuses on what API-first is, how tooling enables it, what design-first is, and the differences between the two.

What is API-first?

APIs are the products and services everyone depends on. APIs are a strategic opportunity. It considers the requirements of today and tomorrow. It accounts for consumer experience

it is a collaboration and incorporation of security and business needs. API first is your storefront, merchandising, and data, and that data’s value is upon consumption. How do we iterate based on proper feedback and collaboration from the end users, whether internal or external? All of this requires a platform and tooling.

Think of API as a business. APIs are your business. It’s your service. It’s what everyone experiences. It is your brand. So that’s why API-first is so important.

Opportunities for premium APIs

  • Monetization of premium APIs. What about enriching your service so you can justify a price increase? Your customer would be happy to pay for it because it has the different attributes to feed the different KPIs so they can drive their business better or know what business value you’re delivering to them.
  • Customization for Complex APIs
  • Competitive differentiation
  • Extensibility and interoperability
  • Modernize, secure and productize

A software platform is about productivity and collaboration. There’s a lot of functionality and key capabilities, but it has to serve that purpose to empower the people that need it.


Everybody likes to code, and even if it’s the same language, it’ll always be in a different way. Nobody likes to document. There are some pitfalls, trials, and tribulations along the way.

Custom code is important. It’s quick. It’s a one-off, a test, a prototype, a test of hypothesis, or proof of value. But how do we harness what we learned from that and iterate? So, if we have to pull back and redo, we are wasting time, which is expensive. There are opportunity costs involved.

We all know APIs in the edge are often unsecured and the most commonly attacked vector in the market. You may have the service mesh and the integration, you have a legacy, you need to interoperate, you have a lot of challenges, and yet you need to go at scale with relative reliability.

API-first does not mean Design-first.

With code-first, there is a business input, and the developers start coding based on that. That is a costly process. Then you build up the API documentation, which could be built on the wrong code, and then you manage incorrect APIs.

Design-first includes more collaboration with the key stakeholders, your key liaisons, and subject matter experts of that domain. It would be nice to have a tool that helps you visualize it in a very simple, abstract way, powered by a designer and a developer. You’re building that design. While you’re building that design, it’s generating the code in a standard way that’s also documented.

If there is a change, you’re pushing it through to a quick approval process after doing some mock testing, and now you’re in front-end development, and your developers are happy.

Why does design-first matter?

Design-first removes silos and involves all API stakeholders around your API strategy.

  • Improved communication
  • Input and feedback by business and customers
  • Product-driven APIs
  • Better developer experience
  • Help drive parallel development
  • Enforced governance and security

Competitive advantages of using gravitee API designer

  • Lower development costs
  • Faster time to market
  • Deliver with exactness
  • Reusability and standardization
  • Happy developers and consumers
  • Drive business value

Luke Lipan
Marketing & Sales Professional that exceeds standards and client expectations, while contributing to a winning team environment. Proven producer who takes pride aligning innovative technologies with high-level strategic initiatives. Specialties: Public Speaking Technical Innovation Solution Selling Training and Coaching Negotiating win-win relationships

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