Introducing Yapi: The Command Line API Client Of Your Dreams

Yapi is Postman, Insomnia or Bruno for the power user.

Yapi is an OSS command line tool that makes it easy to test APIs from your terminal. Yapi speaks HTTP, gRPC, TCP, GraphQL (and more coming soon).

Heads up! Yapi is early, early alpha software

I use yapi daily in my development workflow. However, yapi is a SUPER young project and will have bugs, missing features and rough edges.

If you download yapi, I would LOVE your feedback on how to make it better. Please open an issue if you have any suggestions or find any bugs!

Show me some examples!

POST

This request:

# create-issue.yapi.yml
yapi: v1 # specify yapi version
method: POST # or GET, PUT, DELETE, PATCH, etc.
url: https://api.github.com/repos/jamierpond/yapi/issues

headers:
  Accept: application/vnd.github+json
  Authorization: Bearer ${GITHUB_PAT} # supports environment variables

body: # defaults to JSON body, converted automatically
  title: Help! yapi made me too productive.
  body: Now I can't stop YAPPIN' about yapi!

expect: # supports expected response tests
  status: 201
  assert: # assert using jq syntax
    - .body == "Now I can't stop YAPPIN' about yapi!"

Gives you this response:

yapi run create-issue.yapi.yml
{
  "active_lock_reason": null,
  "assignee": null,
  "assignees": [],
  "author_association": "OWNER",
  "body": "Now I can't stop YAPPIN' about yapi!\n",
  // ...blah blah blah
}

URL: https://api.github.com/repos/jamierpond/yapi/issues
Time: 579.408625ms
Size: 2.3 kB (1 lines, 2288 chars)

[PASS] status check
[PASS] .body == "Now I can't stop YAPPIN' about yapi!"

(Only the JSON goes to stdout, the rest goes to stderr, so is pipeable!)

Yapi supports chaining requests between protocols

Multi-protocol chaining

Yapi makes it easy to chain requests and share data between them, even if they are different protocols.

# multi-protocol-chain.yapi.yml
yapi: v1
chain:
  - name: get_todo # HTTP request
    url: https://jsonplaceholder.typicode.com/todos/1
    method: GET

  - name: grpc_hello # gRPC request
    url: grpc://grpcb.in:9000
    service: hello.HelloService
    rpc: SayHello # Supports reflection if server has it enabled
    plaintext: true

    body:
      greeting: $get_todo.title # use data from previous request

    expect:
      assert:
        - .reply == "hello delectus aut autem" # assert on gRPC response

Run this example in the yapi playground

Integration Testing with yapi

Yapi has built-in support for writing integration tests with expectations and assertions.

yapi: v1
method: GET
url: https://api.github.com/repos/jamierpond/yapi/issues/5
headers:
    Accept: application/vnd.github+json
expect:
    status: 200
    assert:
      - .state == "closed"
      - .closed_by.login == "jamierpond"

Run this example in the yapi playground

Yapi has an LSP Server for IDE Integration

Yapi comes with a Language Server Protocol (LSP) server that provides syntax highlighting, autocompletion and validation for yapi request files in editors that support LSP (Neovim, etc), you can also use the yapi Neovim plugin (still early days).

At some point I'll write the VSCode extension too, please make an issue if you think this is important!

GitHub Actions Support

I use yapi's GitHub Action to run integraion tests on the CI for this blog!

name: Integration Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build Application
        run: npm build

      - name: Run Yapi Integration Tests
        uses: jamierpond/yapi/action@0.X.X
        with:
          start: npm run start
          wait-on: http://localhost:3000/health
          command: yapi test ./tests -a

For example, here is the output of yapi running integration tests in GitHub Actions:

Supports for Multiple Environments

Yapi make it easy to manage multiple environments (dev, staging, prod, etc). Define your environments in a yapi.config.yml file:

yapi: v1

default_environment: local

environments:
  local:
    url: http://localhost:3000
    env_file: .env.local
    vars:
      some_param: default_value

  prod:
    url: https://yapi.run
    env_file: .env.prod
    vars:
      some_param: some_value

Then run yapi with the desired environment:

yapi run my-request.yapi.yml --env prod

This also cleans up your request files a little, now you can use paths instead of full URLs:

yapi: v1
method: GET
path: /api/v1/status # base URL comes from the selected environment

Getting Started with Yapi

To get started with yapi, simply install it using the instructions on the yapi GitHub repository and start creating your first request files!

Contributing to Yapi

Yapi is an open-source project maintained by just me, Jamie. If you find bugs or have feature requests, please open an issue on the yapi GitHub repository. Pull requests are very welcome too!