“Some APIs are loved by developers, others not. The difference is in their developer experience.”

Nicolas Frankel is a Developer Advocate with more than 15 years of experience consulting for many customers in various contexts, usually working with Java/Java EE and Spring technologies but with focused interests like rich internet applications, testing, CI/CD, and DevOps.

In this interview with Nicolas, which took place at the Heapcon tech conference we spoke about APIs, challenges with developing them, and developer experience when it comes to APIs.

Tips and tricks on developing APIs

At the Heapcon conference, you spoke on evolving APIs. Tell us more!

Nicolas: When you create your first HTTP API, you need to think about many things: on top of regular projects, such as deadlines, you have to model your entities, design their boundaries, and then apply all the unspoken rules about REST. Versioning is probably far away from your immediate concern. So when the business comes for v2, you’ll face a huge challenge. My idea is to give developers tips and tricks to help them address this challenge.

In general, developer experience is important when designing software, but when it comes to APIs, it becomes essential

What are the biggest challenges before and after the release of the HTTP API, and how best do you overcome them so there are no unforeseen problems?

Nicolas: I touched on the subject in the previous question, but the biggest is undoubtedly REST. Roy Fielding described REST in his famous thesis. However, beyond simple use cases, tons of practical issues are not addressed in it.

For example, how do you model money transfers between two banking accounts? Is the HTTP method a POST, a PUT, or a PATCH? Or do we come up with a custom HTTP verb? What’s the URL to act upon? Shall we put the target bank account on the path? Should the call be idempotent or not? If yes, how do you implement it?

What is the best balance between ease of use and robustness when it comes to APIs?

Nicolas: It’s a good question, but “it depends”. The tension between ease of use and robustness is not specific to APIs but permeates every product design decision. Depending on the context, the balance may weigh on one side or another; there can be no generic answer to this one.

Developer experience is essential

What are the best practices for designing APIs?

Nicolas: APIs are meant to be the glue between heterogeneous technology. Hence, the first and most important rule is to start with the contract to be as independent of the tech stack as possible.

The dust has settled, and OpenAPI has emerged as the clear winner. While writing the spec itself is not fun, tools exist to make your life easier, e.g., the Swagger editor.

Regarding API design, how much is developer experience essential in those processes?

Nicolas: In general, developer experience is important when designing software, but when it comes to APIs, it becomes essential. While it’s hard to quantify DX, some APIs are loved by developers, while others are not that much. I recommend the book API Design Patterns to avoid making junior mistakes.

What are the best practices for documenting API-s?

Nicolas: 1) Use OpenAPI 2) Use the description and externalDocs fields to your heart’s content. While developers are not particularly famous for writing documentation, it’s what makes the difference in adopting your APIs.

You have over 15 years of experience consulting many companies from different domains. What does a consultant do in techs exactly?

Nicolas: In my context, consulting means being hired by a company that “sells” you to clients on a temporary basis. It definitely teaches you a lot because you’re exposed to different technologies, organizations, approaches, etc. However, I finally quit because most clients had the typical downsides of big organizations: political games, unrealistic expectations, teams you didn’t choose, etc..