Helping Your Users Write Succinct API Calls With "api" ✍️
Tags: devrel, openapi, typescript
Published: 2022-12-21 20:51:09

---
title: Helping Your Users Write Succinct API Calls With "api" ✍️
published: true
description: We’re always looking for new ways to make APIs more accessible and lower the on-ramp to getting started. Today, we’re sharing more about "api", our open-source SDK generator.
tags: DeveloperExperience,OpenAPI,TypeScript
canonical_url: https://blog.readme.com/helping-your-users-write-simpler-api-calls-with-api/
---

 ![Helping Your Users Write Simpler API Calls With "api" ✍️](https://blog.readme.com/content/images/2022/12/Boarding-Plane.psd.full.png)

When it comes to [developer experience (DX) at ReadMe](https://blog.readme.com/why-dx-matters-driving-api-success-with-a-user-first-approach/), two mantras often come to mind:

1. **Awesome by default** 🆒 While developers often benefit from having a slew of configuration options and flags available in their tooling, ***too*** many options can feel overwhelming, particularly for first-time users. Having a sensible default experience will help your developers get to that first successful API call even faster.
2. **Meet users where they are** 🤝 No two developers are alike, so your API ([and your docs!](https://blog.readme.com/onboarding-users-with-personalized-docs/)) should reflect that. Your developers will often have different use cases, different technical stacks, and different levels of experience with APIs. The more your API can accommodate your developers and their diverse needs, the higher your API adoption.

With these in mind, we’re always looking for new ways to make APIs more accessible and lower the on-ramp to getting started. Today, we’re sharing more about [`api`, our open-source SDK generator](https://github.com/readmeio/api).

`api` takes your OpenAPI definition and generates a powerful SDK that’s custom-tailored to your API. With the world-class developer experience that an `api` SDK provides, making API calls has never felt easier or more magical 🪄

## The `api` origin story 💭

You’ve probably heard a lot about APIs, but what exactly is `api` and why does it matter?

Let’s start by looking at a typical code sample for an API call. In this example, the sample is written in JavaScript, and it uses [the Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to [fetch our current job openings from the ReadMe API](https://docs.readme.com/main/reference/getopenroles):

```js
fetch('https://dash.readme.com/api/v1/apply', {
  method: 'GET',
  headers: { accept: 'application/json' },
})
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));
```

ReadMe’s API reference automatically generates code samples for your endpoints in dozens of languages and libraries, including `fetch`. And for good reason too — `fetch` is popular, versatile, and it’s available everywhere!

- It’s baked into every modern web browser (including the one you’re likely reading this on!) 🌐
- It can run on the server out-of-the-box (thanks to runtimes like [deno](https://deno.com/deploy/docs/runtime-fetch) and [Node.js 18](https://nodejs.org/en/blog/announcements/v18-release-announce/#fetch-experimental)) 📦
- It offers a tremendous amount of flexibility to handle a wide variety of API use cases 💪

But this approach isn't for everybody. Since `fetch` and other generic HTTP clients are designed to make calls to nearly every API under the sun, there’s inherently going to be verbosity, boilerplate code, and a whole lot of configuration options. This makes your typical, off-the-shelf HTTP client pretty confusing for many API users.

At ReadMe, we’re constantly keeping an eye on the best DX out there, and we’ve come to notice a trend. Many of the top [API-first companies](https://techcrunch.com/2022/06/18/the-rise-of-api-first-companies-in-fintech-and-beyond/) out there offer their own custom [SDKs](https://en.wikipedia.org/wiki/Software_development_kit), such as [Stripe](https://stripe.com/docs/js), [Twilio](https://www.twilio.com/docs/libraries/js-libraries), and [Plaid](https://github.com/plaid/plaid-node) (and I’m only linking to their JavaScript SDKs!).

Those companies and their respective SDKs are the tip of the iceberg. API-first companies are continually investing in SDKs for a variety of programming languages, and for good reason. With an SDK that’s custom-tailored to a single API, their users have much less boilerplate code and confusing configuration options to deal with, so they can get to that first successful API call even faster.

Thousands of great APIs run their developer hubs on ReadMe, where our customers are already documenting every little detail about their API using [the OpenAPI Specification](https://docs.readme.com/docs/openapi). This got us thinking: “the OpenAPI Specification already provides a ton of valuable information about an API, what if we use this to generate an SDK that’s as good as [Notion’s JavaScript SDK](https://github.com/makenotion/notion-sdk-js)”?

And that, my friends, is how `api` came to fruition. 🌱

## Making ~~fetch~~ `api` happen 💄

Let’s revisit our previous example: fetching current job openings from the ReadMe API. The `fetch` sample we looked at works perfectly fine, but what would an API call look like if the ReadMe API had a custom-tailored SDK? That’s where `api` comes in.

Here’s what [the same API call](https://docs.readme.com/main/reference/getopenroles) looks like with a code snippet using the `api`-generated SDK:

```js
readme.getOpenRoles()
  .then(({ data }) => console.log(data))
  .catch(err => console.error(err));
```

Notice how there is far less boilerplate code than the `fetch` example, and much of the complexity is abstracted away. But the code sample does the exact same thing!

Let’s break down the process of SDK generation, end to end:

1. The ReadMe API is documented using an OpenAPI definition. Within that definition, there is an [operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) with an ID (i.e., `operationId`) called `getOpenRoles`.
2. Anytime an API user (in this case, someone that wishes to [apply for a job at ReadMe](https://readme.com/careers)) runs the installation command to set up the SDK, `api` takes the OpenAPI definition and generates an SDK that’s completely customized to the ReadMe API. It contains methods for every operation available in the API definition, as well as detailed descriptions of every request and response parameter.
3. Once the installation is complete, the user imports the SDK into their code and starts writing. Thanks to the comprehensive TypeScript definitions produced by `api`, code completion platforms like [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense) can guide them along as they write their snippet. They’re able to successfully hit the ReadMe API with a code snippet that’s a fraction of the length and complexity of the corresponding `fetch` snippet.

That’s the developer experience ethos we’re going for with `api`: a readable, succinct code snippet that will get you to that first successful call in a jiffy. 🥜

## Elevate your OpenAPI-powered DX with `api` 📈

One important design consideration as we built `api` is that we wanted the SDK generation to be completely agnostic of your documentation platform, much like OpenAPI itself. Because `api` is built on top of the OpenAPI specification, anybody that describes their API using OpenAPI can step up their DX with a custom SDK generated by `api`.

There are a few requirements to get started:

- [Node.js](https://nodejs.org) and `npm` installed
- A local directory with a `package.json` file created
- An OpenAPI definition, either located in your directory or served from a URL

Once you have everything in order, you can generate a custom-tailored SDK by running the following command from the root of your directory and following the prompts:

```sh
npx api install path-to-api-definition
```

Once the SDK is generated, you’ll be writing succinct code snippets and getting to that successful first API call in no time 🚀

## Two birds 🐦, one incredible DX 🌟

If there’s one thing that developers, technical writers, and pretty much **anyone** enjoys, it’s being able to stretch your work so it goes further and saves you time. And that’s another reason why we’re so excited about `api` and how it leverages the existing OpenAPI ecosystem to supercharge your users’ developer experience in ReadMe.

Before `api` came around, there were already many great ways that a comprehensive OpenAPI definition could set your API reference apart and further set your users up for success:

- Comprehensive security scheme definitions can help your users navigate one of the trickiest parts of getting started with an API: authentication!

![Helping Your Users Write Simpler API Calls With "api" ✍️](https://blog.readme.com/content/images/2022/12/GS-A-Pages-in-Hub.gif)

- Detailed request parameter descriptions and definitions (with default values, enums, and examples!) eliminate ambiguity and help your users understand exactly what data to send to your API:

![Helping Your Users Write Simpler API Calls With "api" ✍️](https://blog.readme.com/content/images/2022/12/CleanShot-2022-12-14-at-13.33.10.gif)

- By capturing exhaustive response schemas and plenty of examples for every edge case, your users will know exactly what to expect from your API’s responses:

![Helping Your Users Write Simpler API Calls With "api" ✍️](https://blog.readme.com/content/images/2022/12/CleanShot-2022-12-14-at-13.38.12.gif)

But who said that a great developer experience should start and end with your docs? By investing in the above aspects of your OpenAPI definition, your users’ experience with your `api`-generated SDK becomes even more magical:

- Thanks to that security scheme definition, passing in authentication credentials into your SDK is a one-liner:

```js
sdk.auth('API_KEY');
```

- Because of those detailed request parameter definitions, passing in request parameters is a much more straightforward exercise that uses a fraction of the boilerplate code. And thanks to the power of TypeScript, users will get helpful cues about the parameters as they write in their editor:

![Helping Your Users Write Simpler API Calls With "api" ✍️](https://blog.readme.com/content/images/2022/12/CleanShot-2022-12-14-at-13.16.15.gif)

- And because of those exhaustive response schemas, users will also be able to leverage TypeScript hints to parse out response bodies:

![Helping Your Users Write Simpler API Calls With "api" ✍️](https://blog.readme.com/content/images/2022/12/CleanShot-2022-12-14-at-13.28.15.gif)

There’s already a tremendous amount of value in putting together a rock-solid OpenAPI definition. With `api`, you get even more developer experience bang for your OpenAPI buck 💸

## Available now in your ReadMe API reference 🦉

If you have an API reference section that’s powered by ReadMe, your users can start writing better API calls with `api` today. They can select **Node** in the language selector and select the **api** library to get started.

![Helping Your Users Write Simpler API Calls With "api" ✍️](https://blog.readme.com/content/images/2022/12/CleanShot-2022-12-14-at-13.30.09@2x.png)

If you run into any issues, check out [our docs](https://api.readme.dev/docs) and feel free to contact us at [support@readme.io](https://www.notion.so/Plan-for-bin-readme-com-2ad33cb9b9aa431abdb2b1bc80028b9c). `api` is proudly open-source (shoutout to [Jon](https://twitter.com/sharpfarts) for your all your hard work on this!) so feel free to open up an issue in [the `api` GitHub repository](https://github.com/readmeio/api).