API-First, API Design-First, or Code-First: Which Should You Choose

You have a great idea for an API that will benefit the business. Where do you go from there?

You could write out the business requirements for the API and then code it. Maybe you decide to describe your API in a specification language first, like OpenAPI. Or perhaps you convince your organization to take your API idea and turn it into an API-first product.

In the end, you want to deliver a great API architecture. The first step is to decide which development approach will help you do that. Let’s go through the API advantages and disadvantages of these approaches.

Three Different Approaches to Building APIs

Code-First

A code-first approach typically involves coding an API from business requirements and then generating a machine-readable API definition from that code. It can also mean implementing the API in code and then creating an API description using comments or annotations or even manually writing a description from scratch. An API code first approach doesn’t mean that you won’t have an API design. Instead, you have a design process that is distributed among various code documents.

API-First

An API-first development means that your organization treats APIs as most important” with the understanding that they are critical business assets upon which the organization operates.

This approach involves designing every API around a contract written in an API description language like OpenAPI. Starting with an API contract ensures the consistency, reusability, and broad interoperability of the resulting API. API first companies are quite popular, and the terminology has become quite the buzzword over the years.

Design-First

API design-first means you describe every API design in an iterative way that both humans and computers can understand—before you write any code. With an API design-first approach, every team speaks the same language, and every tool they use leverages the same API design.

This approach begins with every stakeholder participating in the API design to write an API contract that satisfies all parties. It also ensures humans and machines understand the finished product. With this approach, teams spend a lot of time in the design phase to ensure that when it comes time to start coding, they’re writing code that won’t need to be scrapped and rewritten.

Advantages of Each Approach

API-First and API Design-First Share Advantages

Both API-first and API design-first emphasize the importance of design documents and contracts. They provide a reliable source of truth for API design and development teams. Both approaches have stakeholders getting involved early in the design process before writing any code, providing several advantages, such as:

• Ability to Work in Parallel – You can use API description documents to create mock servers and mock APIs, which allow you to try out API designs and test APIs before deploying them. You don’t have to wait on other teams to complete different phases of the API.
• Ensuring a Positive DX – You can use API description documents and third-party tools to automatically generate things that improve the developer experience, like interactive documentation, client libraries, and SDKs.
• Reduce Development Costs – Fixing issues once the API is coded costs far more than fixing them during the design phase. You can also reduce development costs by reusing components across multiple API projects.

Learn more about API-first vs. API design-first and the benefits of each approach by reading our comprehensive guide.

Benefits of a Code-First Approach

In general, working out your API design before you start coding is usually the best option. However, there are a few benefits to going with a code-first approach, such as:

• Deliver Simple APIs Fast – If you need to deploy an API fast, going right to coding after receiving the business requirements will speed up API deployment. If the API has only a few endpoints or is only for internal use, it may not make sense to spend a lot of time creating a design contract. You can also find tools that speed up code-first processes like testing and deployment.
• Familiarity for Devs – Code-first follows the traditional method of software development that most developers are familiar with. This approach typically has no learning curve because developers don’t have to learn a new language or use unfamiliar design tools to create API contracts.

Caveats

A Key Challenge of API-First

API-first means that the organization treats APIs as first-class citizens, which requires company-wide buy-in—a difficult thing to do as not everyone at the organization may understand the importance and business value of APIs.

To go API-first, you need to educate your organization on the benefits of APIs and what APIs bring to the table. You need to get company leaders to understand the commitment required to go API-first. Getting everyone to understand and agree that APIs should take front and center is a formidable challenge, but one that is often worthwhile.

Disadvantages of a Code-First Approach

In most cases, choosing a code-first approach to build your APIs will lead toquite a few problems, let’s look at a code first vs a design first approach.

• Bottlenecks – A code-first approach typically means developers follow a waterfall model to API development, leading to bottlenecks. Teams working on the API will finish each phase in sequential order, so they cannot work in parallel.
• Useless or Bloated APIs – When you code first and then get feedback after several versions of the coded API, you often end up with bloated APIs that have resources users don’t need. You also run the risk of building APIs that don’t help your customers at all.
• No Documentation – When teams finally finish coding an API, creating documentation that the team must maintain can feel like a giant chore. So, documentation often becomes an afterthought instead of a priority and never gets done.
• Wasted Time and Money – It costs far more to make changes to an already-coded API than to an API design. You tend to have to comb through and write a lot of code to fix the API once you get feedback from users. And if you coded first and didn’t create documentation, you could end up creating new versions of endpoints and APIs because no one on the team remembers how the code works.

Code-first may allow you to create APIs fast, but you can end up with more problems than that speedy process is worth.

API-First and API Design-First Approach: A Perfect Match

If you want to create the most high-quality, consistent APIs possible, and with better API reusability, then you should implement both API-first and API design-first approaches.

Both approaches focus on creating API contracts. So, if you implement one approach, you’re already about halfway to implementing the other within your API design architecture. When you adopt both strategies, you gain all their advantages and then some.

Take PayPal, for example. Not long ago, PayPal went through an API-first transformation at scale, adopting an “APIs are products” mindset. The company implemented a strategy where developers create service contracts using OpenAPI and then build APIs following a design-first methodology as much as possible.

It took some time for the teams at PayPal to reorganize and streamline the API design and development process. In the end, the company gained quite a few benefits by going API-first and following an API design-first methodology. Among the benefits are:

• Developers get customer feedback when they need it, enabling them to continuously improve the consistency and quality of PayPal’s APIs.
• The company reduced infrastructure investment by migrating all APIs to the OpenAPI specification.
• Developers build APIs that are more understandable and usable by consumers outside the domain.

In a recent API Intersection podcast, Jason Harmon and Adam DuVander chatted with Jay Jena, Head of API Platform at PayPal, about PayPal’s API program. Jay explained that PayPal has established a detailed design guide to ensure the consistency of every API. He said that:

“We have an API tooling blueprint that is standardized. It makes things consistent—whether it’s REST, GraphQL, events-based, or any other type of API.”

Teams at PayPal run every API through a linter and it automatically adds everything the teams want to do, such as documentation text, OpenAPI conformance text, and security text. The linter validator grants pull requests, so if a request has any errors, the validator won’t allow it to go through until the developer corrects them. Everything is enforced through the linter validator to ensure developers follow the API design guidelines.

Your organization doesn’t have to be a large enterprise like PayPal to implement API-first and API design-first approaches to building APIs.

Stoplight’s collaborative cloud tools allow organizations of all sizes to implement and streamline their API design and development process. With Stoplight’s tools, you can build products following both the API-first and API Design-first approaches. Enjoy a better API experience!

Additional Resources

• What is OpenAPI? OpenAPI Definition & OpenAPI Standards
• API Design-First vs Code First
• 4 Reasons Why You Should Approach APIs with a Design-First Mindset
• Is API Planning the Same Thing as API Design
• How to Create an API in Three Steps
• OpenAPI Powered Mock Servers for Faster Development
• API Versioning Has No “Right Way”
• Untangling an API-First Transformation at Scale. Lessons Learnt at PayPal – Part 1
• Untangling an API-first Transformation at Scale. Lessons Learnt at PayPal – Part 2
• Untangling an API-First Transformation at Scale. Lessons Learnt at PayPal – Part 3
• For more on API lifecycle methodology, visit our API Design Hub