DEV Community: Kanad Gupta

Authenticating Into ReadMe’s CLI With 1Password and Your Fingerprint ☝️

Kanad Gupta — Thu, 04 May 2023 15:53:29 +0000

Long-time followers of the ReadMe blog know I have been absolutely shameless in my love for 1Password. It's a great password manager that we use here at ReadMe to securely store shared logins, API keys, and more. Staying secure online is increasingly difficult these days, and we’ve been able to safely rely on 1Password for best-in-class security with a convenience and user experience that lives up to one of our core ReadMe values: “strive for simplicity.”

So it should come as no surprise that I’m very stoked to announce ReadMe's partnership with 1Password. With the ReadMe shell plugin for the 1Password CLI, together we’re making your experience with ReadMe’s developer tools even more convenient and secure. Get the details below! 🤝

Juggling API keys: a necessary DX evil 🤹

Let’s first start with some background. Over the last year or so, we’ve been making several improvements to the developer experience around API keys in ReadMe:

A secret scanning partnership with GitHub to automatically revoke exposed ReadMe API keys and notify our users ♻️
The ReadMe API key management dashboard which gives you the ability to provision multiple keys for your project and makes it easier to rotate keys out 🔄
Interactive Getting Started and Authentication pages in the API reference section, where you can browse your ReadMe API keys and make authenticated requests to the ReadMe API directly from the docs (and yes, you can also set these pages up for your users!) 🔑

While these changes have been great from a security and developer experience standpoint, none of these could possibly address a common problem amongst developers: juggling lots of API keys. Figuring out where keys came from, rotating keys, maintaining separate keys for separate environments/users…the list goes on! It’s a necessary evil for developers when a key inevitably gets leaked 🙀

The Getting Started and Authentication pages in the API reference 🔑

Our knowledge base has grown to the point of switching over to a multi-project setup for our docs. Because of this, we’re now working with many API keys across several ReadMe projects, which is also the case with many of our Enterprise customers. And once you start dealing with multiple API keys that you’re sharing with your team, it can get chaotic rather quickly.

1Password has proven to be a useful management tool for API keys not only because of its security, but also because you can jot down notes for a given API key. You can use this to provide helpful context for fellow engineers, like expiration dates, links to management dashboards, where it’s used, etc. While it’s easy enough to store these credentials in your password manager, what about using your password manager as the single source of truth so you can load secrets into your developer environments in a secure, automated way?

When adding an API key to 1Password, include detailed notes for context — your fellow engineers will thank you!

Luckily, 1Password introduced shell plugins, which are integrations that securely pass API keys into your favorite command line tools, including gh (the GitHub CLI), twilio (the Twilio CLI), and (you can probably guess where I’m going with this…) rdme (the ReadMe CLI)! Let’s dive into the ReadMe shell plugin below.

Say hello to the ReadMe shell plugin 🐚

With the ReadMe shell plugin set up, you can keep your ReadMe API key in 1Password and securely pass it into your rdme commands. What does this look like in practice? A quick scan of your fingerprint (if you’re a macOS user):

Pretty slick, right? Let’s walk through how this all works:

First, make sure you have the latest version of rdme, the 1Password desktop app (Mac or Linux only), and the 1Password CLI (version 2.12.0 or above) installed 💿
Next, set up the ReadMe shell plugin for the 1Password CLI. This will create (or import, if it already exists) a 1Password item that contains your ReadMe API key 🐚
Once everything is set up, 1Password CLI will listen to your terminal for rdme commands that require authentication (i.e., authenticated commands like rdme openapi are listened for and non-authenticated commands like rdme --help will be ignored) 👂
When a rdme command is executed that requires authentication, the 1Password CLI will prompt you for your fingerprint (or whatever authentication setup you have for the 1Password app) ☝️
The 1Password vault is unlocked, your ReadMe API key is securely passed into the terminal command, and rdme is connected to your ReadMe project 🚀

While this approach to passing credentials into rdme is both convenient and secure, do you want to know what’s my favorite part about this experience? If you’re juggling many API keys across several ReadMe projects like we are, you can store all of them in 1Password and have the ReadMe shell plugin confine your credentials to a specific directory or terminal session.

With the ReadMe shell plugin, you’ll be an expert API key juggler in no time!

Some bonus “action” 🎬

But wait, there’s more! As an added benefit of securely storing API keys in your 1Password vault, you can safely load them into CI/CD environments, like GitHub Actions. This is great news, because rdme happens to have first-class support for GitHub Actions!

Here’s yet another great example of how 1Password and rdme can work together in harmony to securely sync a directory of Markdown files to ReadMe:

# Runs on every push to the `main` branch
on:
  push:
    branches: [main]

jobs:
  sync-to-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Load secret from 1Password
        uses: 1password/load-secrets-action@v1
        with:
          # Export loaded secrets as environment variables
          export-env: true
        env:
          OP_CONNECT_HOST: <Your Connect instance URL>
          OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
          RDME_API_KEY: "op://engineering/readme/api-key"

      - name: Sync OpenAPI file to ReadMe 🦉
        uses: readmeio/rdme@v8
        with:
          # `rdme` automatically reads the `RDME_API_KEY` env variable
          rdme: docs ./documentation

Let’s break down what’s happening in the example above:

This workflow kicks off when a commit is pushed to the main branch of your GitHub repository.
1Password’s GitHub Action establishes a secure connection to 1Password, grabs the ReadMe API key value and exports that as an environmental variable called RDME_API_KEY.
The rdme GitHub Action automatically detects RDME_API_KEY as an environmental variable containing your ReadMe API key, and uses that to sync your Markdown docs (located in the documentation/ folder) to your ReadMe project.

With the power of 1Password and rdme, you can securely sync your docs to ReadMe — whether you’re working in the command line or in a GitHub Actions runner 😌

Now let’s get you plugged in 🔌

Ready to start syncing? The integrations described above are available now:

Head over to the 1Password Developer docs to get the ReadMe shell plugin up and running 🐚
Check out our docs on setting up the rdme GitHub Action and 1Password’s docs on loading secrets into your GitHub Actions workflows 🌊
Check out my appearance on the "The Developer Special" episode of 1Password's "Random but Memorable" podcast. We have a wide-ranging conversation about 1Password's developer tools, developer tools in general, and upcoming projects we're cooking up here at ReadMe 🎙️
Join us on May 11th in SF at API Mixtape, where we'll be talking all things developers with folks from 1Password, Twilio, and more. Use the code 1PASS for a free ticket (hurry, just a few of these codes are available!) 📼

We’re always looking for ways to make ReadMe’s developer tools safer and more enjoyable to use. If you have any feedback about your ReadMe experience, feel free to reach out to us at support@readme.io or open up an issue in the rdme repository. We’d love to hear from you! 🦉

Helping Your Users Write Succinct API Calls With "api" ✍️

Kanad Gupta — Wed, 21 Dec 2022 20:51:09 +0000

When it comes to developer experience (DX) at ReadMe, two mantras often come to mind:

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.
Meet users where they are 🤝 No two developers are alike, so your API (and your 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.

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 to fetch our current job openings from the ReadMe API:

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 and Node.js 18) 📦
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 out there offer their own custom SDKs, such as Stripe, Twilio, and Plaid (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. 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”?

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 looks like with a code snippet using the api-generated SDK:

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:

The ReadMe API is documented using an OpenAPI definition. Within that definition, there is an operation with an ID (i.e., operationId) called getOpenRoles.
Anytime an API user (in this case, someone that wishes to apply for a job at ReadMe) 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.
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 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 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:

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!

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:

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:

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:

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:

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

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.

If you run into any issues, check out our docs and feel free to contact us at support@readme.io. api is proudly open-source (shoutout to Jon for your all your hard work on this!) so feel free to open up an issue in the api GitHub repository.