DX, API Design & Documentation

Simplifying Consuming APIs for SDK Haters

248views

Darrel Miller has worked at Microsoft on APIs for close to 30 years. He has been working with the Open API specifications team on being an editor of that specification. In this article, he discusses simplifying consuming APIs for SDKs.

There are many complaints about SDKs and a lot of pain around using SDKs to call APIs. Developers don’t want to have to learn a new SDK every time they try and use a new API. It’s frustrating when the SDK isn’t available in your language, or it’s out of date, or it’s poorly implemented, or maybe it works fine, and it’s up to date, but then you try and pull it into your application, and there’s a dependency that it uses.

So, if there is so much pain, why do we have SDKs? We have SDKs because 50% of developers will not want to use APIs if they do not have SDKs that they can use. Sometimes, API developers spend more time building SDKs to make them developer-friendly than on building APIs. But you need not create a custom SDK for each API if you use the GraphQL client. It uses the API description to know how to call a particular API or gRPC.

You can create a stub. I think 20 years ago, we had this in SOAP. You could point a tooling to a WSDL endpoint, and it would generate a client for you. But, if the API is updated the next day, chances are that the client won’t work anymore. So, there are pros and cons.

Ironically, the API world is behind the curve on this. ¬†We spent many years arguing over the right API description to use, and it’s taken a while for open API to become the de facto API description format.

We’re just starting to see some interest in solving this problem of producing SDKs, which is expensive and painful. Still, most of the efforts I’m seeing today are focused on the API producer being the customer of this tooling. In my opinion, we’ve been building for the wrong customer. It should be the API consumers who can choose their tooling for generating client code for an HTTP API. They should only have to learn that single tool to get a consistent experience across their APIs. No matter which API they’re using, they should be able to get a similar API surface. API consumers shouldn’t have to wait for API producers to produce an SDK to get a great experience with the API they want to call.

According to the Postman 2023 survey, only about 15% of APIs are public, and internal developers consume the others. Imagine if our internal developers can get SDKs produced for them. This was the realization my team came to when we were building the tool. We decided to stop building a tool where we were the primary customer, and we built a tool that our customers could use to create their client code for our API. The tool still works for building SDKs, and we use it for that, but it’s a business we want to get out of. We believe we can build a better experience for our customers by enabling them to self-serve, but that’s not a change that can happen overnight.

So, we built a tool for you, the API consumer. It’s fast. There’s a command line tool, a VS code extension for a UI experience, and a Docker container. Thousands of developers have downloaded the extension, and the command line tool has been downloaded hundreds of thousands of times. We use it for our own internal APIs and external APIs.

This is an open-source project. We’ve had many external contributions. Red Hat has been a significant influence on our Java implementation. We currently support seven languages and have experimental support for two others.

It is a very opinionated tooling about the shape of the API surface it generates. We reflect HTTP concepts into your programming language. We make no effort to hide the fact that we’re making HTTP calls, we want you to wrap our generated code with an interface that matches the use case and the style that your application and your team work in. You will need that interface to mock the APIs, so why not build that interface to separate it? Create that separation of concerns. You don’t want our generated code to be deeply intertwined with your application code.

We have had many customers asking us to tweak our code. But we’re not in the business of enabling API producers to create beautifully crafted experiences for their specific API. We are in the business of creating a consistent experience for an API consumer, no matter what API they are using, and we care deeply about producing code that’s resilient, reliable, and performant, and that’s difficult to achieve when you’ve got hundreds of knobs and switches and templates where you created yourself so many different code paths to achieve the same thing, but this slightly different style of doing things.

If you don’t like our style, you can take our code and hide it behind the interface using adapter code. If even that does not work for you, you can fork the project, as it is open source. If we want to get the most out of HTTP, we need to stop rewriting all the basic plumbing again and again for every API.

The problem is that API producers are too busy generating, packaging, shipping, and supporting SDKs in several languages to have time to move forward. One of the things that we discovered on this journey to move towards focusing on the API consumer is that API client code and its generation is only one piece of the puzzle. No matter how big or small an API is, most consumers do not call every single operation in our tooling. We ask the consumer to select the operations they want to call, and then we generate the code just for those operations. From a security perspective, instead of having multiple libraries from multiple providers, you’ve only got one software provider to be concerned about with the tool.

To conclude, API producers have more important work that they need to do. As API consumers, we need to up our game and leverage Open API to build better tooling that will work for any HTTP API.

Darrel Miller

Darrel Miller

API Architect on Microsoft Graph
I am a HTTP API Architect. At Microsoft, in the OpenAPI Initiative and at the IETF, I help to drive API standards and improve developer experience across the entire API lifecycle. At Microsoft my role is to guide teams who are creating APIs for our SAAS offerings to produce, reliable, scalable, consistent and easy to use APIs. I work with groups across the company to improve the developer experience for those who are trying to integrate applications with our products and services. Within the OpenAPI Initiative I help to define the direction of the OpenAPI Specification and other API related specifications. I have been an active editor for the last 5 years. At the IETF I co-chair the HTTP API working group. This group has the charter to deliver API standards and guidance to the technical community to encourage better and more interoperable APIs. I have more than 25 years of experience in building distributed business applications on the Microsoft platform. For the last 15 years I have focused on getting the most out of HTTP as a distributed application protocol for building rich business applications. I enjoy helping developers learn technical material, solve problems and help their users be more productive.

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