api v7 — coming soon! 🤘🏽

[kanadgupta]

Hey everyone! We wanted to provide y'all with an update on what we've been cooking up lately ⏲️

We've spent the last few weeks making lots of quality-of-life improvements to the code generation process and the generated SDKs themselves. We're still not quite finished yet, but we're excited to announce that the next major version of api is right around the corner!

Here's what you can expect:

• We've totally overhauled our SDK generation strategy so the generated SDK's types and module resolution should be consistent across all modern¹ JavaScript environments (CommonJS, ES Modules, TypeScript, etc.). The CLI no longer asks confusing configuration questions about the type of JavaScript SDK you want to generate — it now generates a fully-typed JavaScript SDK that ✨ just works ✨ in pretty much every modern JavaScript environment.
• New api CLI commands to help you better manage your SDK installation(s) — commands to list, rebuild, uninstall your SDKs.
• Lots of little DX niceties (license generation, configuration files with sensible defaults, etc.) so you can generate and publish a high-quality SDK to the NPM registry within minutes 🚀

Anything else you'd like to see? We'd love to hear your thoughts — feel free to leave a comment below! Also, if you could take a second to answer the poll below, we'd love to understand how you're using api-generated SDKs in practice.

Thanks for your feedback thus far — excited to see what y'all build with api v7!

-Kanad and the ReadMe team 🦉

Footnotes

1. Note that api v7 will require Node.js v18 or greater if you're a Node.js user, and TypeScript 5.2 if you're a TypeScript user. ↩

[jimmymcpeter]

I came across this library from Wistia's docs and was excited to try it. I ran into issues using it from my ESM package in Node v18 and was ready to use raw node-fetch/axios until I saw your comment on #604 to use api@next. I was able to use npx api@next install https://dash.readme.com/api/v1/api-registry/1sia28loivyd0b and now have a proper SDK with typings and autocomplete -- thank you for this upgrade

[kanadgupta]

Great to hear it's working for you @jimmymcpeter!

[elongberg]

Using this for the first time with 7shifts, TypeScript 5.2 and commonjs module, had a few issues at first with the api 6.1.1 version but switched to npx api@next install @7shifts/v2.2023.0501#1mj6ytblo5wg4q4 and everything just works!

Just a few changes I'd like to see so far:

1. The currently generated code exports a single instance of the SDK. However, we need multiple concurrent instances of the SDK each with a different .auth(...) setup. It's my understanding that the v6 api supported this with something like const client = sdk(...), but that's no longer the case. We're working around this by tweaking the generated index.ts, but it would be nice if we didn't have to.
2. This is a bit of a special case, but 7Shifts isn't a valid identifier. The generated code snippets to try out don't consider that, i.e.

import 7Shifts from '@api/7shifts';

7Shifts.auth('token');
7Shifts.auth('token');
7Shifts.whoAmI()
  .then(({ data }) => console.log(data))
  .catch(err => console.error(err));

3. Perhaps related to the above: we've had to do some finagling to get the importing working. This is BEFORE any changes mentioned above:

import * as fauxAPI from "@api/7shifts";
const api = (fauxAPI as any).default as typeof fauxAPI;
api.auth(...);

[ben-pr-p]

Hi all, any timeline for release?

I'm getting this error: #698

With .postUsers_list using npx api install "@solidarity-tech/v1.0#qsba52hlzrqusc0" --lang ts --yes, and not sure how to proceed.

[kanadgupta]

Hi there — v7.0.0-beta.11 includes this change. Appreciate your patience!

[kanadgupta]

Hi there — v7.0.0-beta.11 includes this change. Appreciate your patience!

[RopoMen]

I was generating SDK with the latest version and got following error while building. I also noticed that all generated files were .ts but imports were done explicitly as .js and nothing worked.

✖ Compiling your SDK
Command failed with exit code 1: npm run prepare
✘ [ERROR] Expected ";" but found "with"

    src/sdk.ts:4:41:
      4 │ import definition from '../openapi.json' with {
        │                                          ~~~~
        ╵                                          ;

✘ [ERROR] Expected ";" but found "with"

    src/sdk.ts:4:41:
      4 │ import definition from '../openapi.json' with {
        │                                          ~~~~
        ╵                                          ;

ESM Build failed
Error: Build failed with 1 error:
src/sdk.ts:4:41: ERROR: Expected ";" but found "with"
    at failureErrorWithLog (/Users/XYZ/repo123/node_modules/tsup/node_modules/esbuild/lib/main.js:1649:15)
    at /Users/XYZ/repo123/node_modules/tsup/node_modules/esbuild/lib/main.js:1058:25
    at runOnEndCallbacks (/Users/XYZ/repo123/node_modules/tsup/node_modules/esbuild/lib/main.js:1484:45)
    at buildResponseToResult (/Users/XYZ/repo123/node_modules/tsup/node_modules/esbuild/lib/main.js:1056:7)
    at /Users/XYZ/repo123/node_modules/tsup/node_modules/esbuild/lib/main.js:1085:16
    at responseCallbacks.<computed> (/Users/XYZ/repo123/node_modules/tsup/node_modules/esbuild/lib/main.js:703:9)
    at handleIncomingPacket (/Users/XYZ/repo123/node_modules/tsup/node_modules/esbuild/lib/main.js:762:9)
    at Socket.readFromStdout (/Users/XYZ/repo123/node_modules/tsup/node_modules/esbuild/lib/main.js:679:7)
    at Socket.emit (node:events:519:28)
    at addChunk (node:internal/streams/readable:559:12)
CJS Build failed

[RopoMen]

Tested

npx [email protected] install .api/myAPI.yaml --identifier myApi                                                           [2025/04/8T8:57:27]
Need to install the following packages:
[email protected]
Ok to proceed? (y) y
✔ Fetching your API definition
✔ Generating your SDK
✔ Saving your SDK into your codebase
⚠ This generator requires some packages to be installed alongside it:
  › @readme/api-core: The core magic of your codegen'd SDK and is what is used for making requests. https://npm.im/api
  › tsup: Used for compiling your codegen'd SDK into code that can be used in JS environments. https://tsup.egoist.dev/
  › typescript: Required for `tsup`.
✔ OK to proceed with package installation? … yes
✖ Installing required packages
Command failed with exit code 1: npm install --save /Users/XYZ/REPOSITORY/packages/backend/.api/apis/aml
npm ERR! Cannot set properties of null (setting 'dev')

Generation goes through pretty ok, but still index.ts is importing sdk.js even though folder contains only sdk.ts and same goes to schemas.ts which imports schemas/schemaxyz.js and schemas folder contains only .ts files. So those imports cannot work.

[RopoMen]

I manually removed all .js extensions from imports but still there was issues in package.json level definition. I tested otherwise solution by importing import myApi from 'packages/backend/.api/apis/myApi/src'; directly from generated stuff (with manual .js import fix) and then things started to work.

So generated code kind a works but there is still some issues to get it completely working.

[kanadgupta]

We're a little bit strapped for capacity to look into this at the moment, but a repository that reproduces this issue (that includes info on the Node.js and TypeScript versions you're using, as well as the OpenAPI definition you're attempting to build an SDK for) would be helpful if you could create one for us!

As for the .js file extensions that point to TypeScript files, that is by design and should work with any up-to-date Node/TypeScript setup. Matt Pocock has a good write-up on the reasoning here: https://www.totaltypescript.com/relative-import-paths-need-explicit-file-extensions-in-ecmascript-imports

[erunion]

I've definitely seen the npm ERR! Cannot set properties of null (setting 'dev') error before and if I recall right it's because we tried to run npm in a package with workspaces set up.

What version of npm do you have installed, or do you actually use yarn in your application?

[RopoMen]

We have npm workspaces in use as well. Unfortunately I cannot provide reference repository that would cause this issue. Simply I have no time for this.