Many folks in the API space promote the idea of design-first, in which the API is designed before the code. This is inherently a user-centric process, as you must consider the API schema and how developers will interact with the interface early on. Compared to code-first, there are many benefits of taking a design-first approach to API development, including promoting collaborative development, catching errors early on, and improving the developer experience.

However, design-first is quite rare in practice. Developers are often pressured to deliver features and might quickly rush to code. Or, you may be dealing with legacy code or simply wrapping a pre-existing internal database, which might not necessarily need the upfront effort and review process that specification-driven development requires. But without a consistent API design process, you could end up with shaky integrations and even forgotten shadow endpoints.

I recently connected with Terence Bennett, CEO of DreamFactory, to learn more about an alternative style: API generation. According to Bennett, the battle against code-first is still an ongoing struggle, but there are some use cases where a data-first approach is permissible. Below, we’ll weigh the benefits of user-driven designs versus data-driven designs and consider how API generation is like DevOps for APIs — especially for data-source, private APIs.

Terence Bennett, CEO of DreamFactory, extols the benefits of API generation.

Let’s set the stage with a reality check. People passionate about APIs seem to assume everyone is doing design-first. What is it really like on the ground?

Based on my conversations across the industry, many still believe the battle against “code-first” is alive and well. Data from the Postman 2023 State of the API Report tell the same story. Although 59% of teams see APIs as products, 26% do not, and 15% couldn’t even answer the question directly. I see the design-first movement inextricably linked to viewing APIs as products, so I would say there is still a lot of work to be done.

What is a data-centric design, as opposed to a user-centric design, as you call it?

Data-centric design is the idea of starting with the data layer or data schema and then working from that model to create an API. This method allows you to borrow that data schema and, using technology like API generation, quickly automate your backend or private API infrastructure.

This is opposed to user-centric API design, which is what most of us are used to thinking of when it comes to API design. In this model, you start with the API consumer’s use case, then build client requirements from that, and then build any necessary relationships with the data. This is a highly flexible approach that requires more time and specific API design skills. This method is necessary when building public APIs or APIs that are going to leave your organization. You must also be consistent with existing APIs and documentation and maintain consistency over time.

What is API generation?

Well, G2 defines API generation as “software [that] allows users to rapidly create and deploy application programming interfaces (APIs) in a secure environment. With this tool, users set desired parameters for an API using a low-code interface while the underlying software scripts the logic and configuration.”

I would add that while API generation might allow for the use of little to no code, these are not no-code tools. Much like a DevOps tool, these are architectural tools that require a technical background to implement properly.

What are some of the limitations or drawbacks of going all in on an OpenAPI-driven, design-first strategy?

I see very few limitations or drawbacks to going OpenAPI-driven and design-first. These are open and accepted standards that have and will stand the test of time. That being said, we can also leverage a different approach to OpenAPI-driven and design-first: API generation.

The traditional method requires designing and then writing an OpenAPI specification from the consumer requirements. Another way of describing this is user-driven design.

API generation flips this model on its head, and it designs the API from a data-driven model. It literally maps the database schema directly into an API schema and generates a live API without writing an OpenAPI specification. You start with the database and completely automate the generation of the API using the OpenAPI standard, along with automating unit tests, full OpenAPI documentation, and security (RBAC, key management, rate limiting, and authentication).

While the user-driven design approach is ideal for any public APIs. We think the data-driven approach is ideal for data-source, private APIs, which often make up a considerable portion of an organization’s infrastructure.

The last Postman report found that 61% of APIs being developed today are private, with only 14% public-facing. Many of these private internal integrations are just wrappers on databases. Do such internal APIs really always need a lengthy design-first review process?

We don’t think so. We think, in these cases, pivoting from a user-driven design approach to a data-driven design approach can yield massive gains for a team. It streamlines security and logging/monitoring for private APIs, ensures all private APIs have robust and up-to-date documentation, makes discoverability easy, and minimizes cases of zombie APIs.

What are the potential benefits of using RESTful API generation techniques that don’t adhere to user-first design methodology?

Well, I think it’s useful to focus on the concerns highlighted in the aforementioned Postman State of the API report around obstacles to producing APIs. The top four are lack of people, lack of time, lack of API design skills, and lack of documentation.

API generation allows your API development team to focus on higher-value, directly revenue-moving projects because they can automate large parts of their private API backend.

In some cases, I’ve seen a team of two senior architects generating and managing hundreds of private APIs. API generation is all about automating away the repeatable tasks, like setting up and managing roles, keys, rate limiting, and authentication through a simple UI.

Our API development teams have a highly specialized set of skills, and we need to do a better job of putting their effort where there is the most business value. API generation gives organizations a DevOps-like automation capability to streamline and automate their whole backend private API infrastructure. This allows those teams to do more with their time, thus accelerating higher-priority projects.

What are cases where APIs should definitely adopt design-first principles? (For example, public-facing REST services, and API-as-a-products)

Design-first principles, more specifically user-centric design, are critical whenever you are exposing public REST services. These practices will help ensure a deep focus on the consumer and consistency across an organization’s different endpoints, data structures, and documentation.

Any other best practices or advice you’d like to offer when considering using API generation instead of design-first?

API generation is really about DevOps for APIs — to be even more explicit, DevOps for data-source, private APIs. When properly implemented, it helps organizations better secure and safeguard data and allows API development teams to accelerate projects.