In the ever-evolving landscape of software development, buzzwords and paradigms come and go. One such term that has gained significant traction in recent years is "API-First Development." It's been hailed as the holy grail of modern software engineering, promising to streamline the development process, enhance collaboration, and deliver scalable and flexible solutions. But, is it really the silver bullet it's often portrayed to be?
In this blog post, we'll embark on a journey to explore the API-First approach in depth, dissecting its principles, benefits, and potential pitfalls. We'll also shed light on alternative development approaches.
What first?
In the history of software development, choosing the right words has always played a crucial role in ensuring clear comprehension. This is particularly evident when we talk about APIs, where it's apparent that people within the community don't always share the same understanding of specific terms. "API first" is a prime example of such a term. It signifies that an organisation has devised strategies and methods to give top priority to APIs within its operations. This shift in perspective essentially makes APIs a central component of the organisation's business model. However, it's worth noting that the term "API first" doesn't hold much significance for development teams.
When it comes to API development, concepts like "design first," "code first," and "prototype first" carry significant weight within a development team. Essentially, it's crucial for every team member to grasp that APIs primarily serve as a means of transporting data. This stands in sharp contrast to API development, which revolves around deploying a fully developed service alongside its corresponding API. So, the question arises: How do we harmonise these layers of data and APIs?
APIs are not the panacea
To begin, it's crucial to grasp that APIs don't offer a universal solution. It's essential to acknowledge that APIs may not always be the best tool for the job in certain circumstances. Additionally, we should consider all potential security concerns outlined in the OWASP Top 10 throughout the development process. Moreover, it's advisable to minimise the number of dependencies integrated, which should also involve carefully assessing the complexity of the API. The organisation should also prioritise catering to the users of a specific API. These users are primarily interested in transferring data and carrying out various functions.
Data and APIs - Two sides of a medal become one
In organisations, there's often a strict separation between data and API initiatives. At times, it seems like this division is in place to prevent innovation and change. However, when we explore the concepts of data mesh, we realise that the ideas surrounding data products and data contracts can also be incredibly beneficial within the context of API initiatives. We often discuss the idea of good APIs or high-quality API products. In my opinion, these APIs simply require solid data products to be able to make the same claims for themselves. If we use data contracts as the foundation for our further discussions, we can derive the necessary data models for our API descriptions from these contracts. This approach opens up opportunities for automating all the processes described earlier, making data operations much more efficient.
Focus on Developer Productivity
Now, let's circle back to the development teams and their productivity. When we discuss API definitions, these typically come in the form of YAML or JSON files. But, do development teams genuinely want to be dealing with these manually? Ideally, these files should be treated as artefacts generated through automated processes. Regarding data models, taking a code-first approach to create APIs initially makes sense to avoid burdening teams with design tasks upfront. If we have well-coordinated teams, this doesn't necessarily result in a decrease in speed, as teams can kickstart with a dedicated development stack. Similarly, it doesn't imply the absence of a governance-supported development process but rather that it's well-documented and includes guidance and support.
Interface first
If we delve deeper into this, it becomes evident that relying solely on a code-first approach might not always be the best course of action. Instead, consider shifting towards a design-first approach by treating the respective endpoints as agnostic interfaces. This approach allows us to regain focus on the design aspects. Additionally, by utilising data products, we gain insights into the specific interfaces required for these data products, as detailed in the descriptions under the output ports.
Now, when it comes to implementing the agnostic description, we have the option of leveraging two open-source tools: Microsoft TypeSpec and TaxiLang. The latter is also employed by Orbital for data description purposes. TypeSpec closely resembles TypeScript in terms of syntax, making it particularly user-friendly for developers with a background in TypeScript. For a more comprehensive understanding of TypeSpec and TaxiLang, I recommend checking out two of my previous posts on the codecentric blog.
To fully embrace the interface-first approach, we must expand the existing API operations pipeline to accommodate a data engineering workflow and a transformation workflow tailored for the agnostic description. Furthermore, we should consider making the API Operations Pipeline accessible for other interaction patterns as well.
Conclusion
In summary, the key takeaway here is to ensure we don't mislead the development team regarding the buzzword "API first." Instead, it's essential to have confidence in their existing skills. What becomes even more critical is shifting the team's focus towards being more consumer-centric. Subsequently, we can introduce them to the concept of "interface first" and guide them onto the path of "design first." Through this post, we can also understand that APIs aren't merely about skills and tools; it's about putting people at the forefront of all our development efforts once again.
References
Charge your APIs Volume 10: Crafting API Definitions with TypeSpec Charge your APIs Volume 11: Taxi Language - Building APIs with Precision and Ease
Was this post helpful?
More articles
fromDaniel Kocot
16.4.2024 Your job at codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
More articles in this subject area
Discover exciting further topics and let the codecentric world inspire you.
Gemeinsam bessere Projekte umsetzen.
Wir helfen deinem Unternehmen.
Du stehst vor einer großen IT-Herausforderung? Wir sorgen für eine maßgeschneiderte Unterstützung. Informiere dich jetzt.
Hilf uns, noch besser zu werden.
Wir sind immer auf der Suche nach neuen Talenten. Auch für dich ist die passende Stelle dabei.
Blog author
Daniel Kocot
Senior Solution Architect / Head of API Consulting
Do you still have questions? Just send me a message.
Do you still have questions? Just send me a message.