npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

api-vcr

v0.1.27

Published

Record API responses for later. Work from a plane, island, or submarine. No internet needed.

Downloads

4

Readme

Record and Play Back your API

This records API responses so you can play them back later, quickly and reliably.

If you're a front-end developer this means you can develop without an API server--even without the internet.

You can also write tests for front end components that have some API dependencies but shouldn't break if the API server has hiccups.

It's good for:

  • Testing (Responses are always the same, and fast)
  • Nomads (Work on JS apps without internet)
  • Unstable APIs (the VCR smooths out API downtimes)
  • Throttled APIs (don't get shut down for querying too much while developing)
  • Coordinating with frequent back end changes that require 30 minutes of API downtime to rebuild and deploy (ahem).

This is similar to some other projects. Other projects might be better for your needs, but some things make this one different:

  • Other solutions are focused on testing. That's great and valid, but I want to develop against something fast, deterministic, and reliable, too.
  • This is written in Node, so it's easy to fit in with a front end developer's workflow.
  • I store the responses as plain text JSON files so you can modify them whenever you want, and see very clearly where I create bugs or mismatch your expectations on API paths.
  • You can fake out your own API by making a tree of json files. No recording necessary. That could be pretty useful, huh?
  • Supports multiple API servers. You just run multiple instances and it stores data in a folder tree by hostname and port.

Installation

This module is a dev tool with a command line interface, so it is installed globally.

npm install -g api-vcr

I'd actually prefer it to be local to a project, but there's no way to provide a nice CLI API in a locally installed node module. You'd have to type ./node_modules/.bin/api-vcr all the time (plus args), and I don't want to do that to you. This is actually why grunt-cli exists, I now understand.

Quick Start Guide

First let's launch in record mode so we can pass through requests and record the responses.

To run in record mode:

api-vcr http://jsonplaceholder.typicode.com/ --record

Now lets hit some endpoints so we can get a nice set of data.

In a browser, you can drop in these urls, or any from the jsonplaceholder api:

For each request, the VCR will create a single JSON file, using the request information to name the file.

For example, the request:

GET http://localhost:59007/posts/1/comments

Is mapped to the file:

./api-vcr-data/jsonplaceholder.typicode.com/80/posts/1/comments.json

After making requests to localhost with the recorder running, you should see the log saying that files are being written, and you should be able to explore a tree of easy to see, editable JSON files. You can change these manually if you want. Be aware the recorder will overwrite them if you run it again later.

Go ahead and kill the server now. Ctrl+C.

Armed with recorded data, you're ready to run in offline mode.

api-vcr http://jsonplaceholder.typicode.com

Now any request you've previously recorded returns instantly from disk:

Similar requests you haven't recorded yet return their best guess:

Totally new requests 404:

Options

You can specify a port for the vcr server to listen on. This is useful for running more than once instance. The port of the API server is used by default (unless that port is 80), this makes keeping proxies straight a little easier if you have remote APIs identified only by port number.

Set the port:

api-vcr http://myapi.com:8080 --port=1337

By default, data is stored wherever you run the command. If you always run the command from your project dir, this works well.

You can also set a hard-coded data path:

api-vcr http://myapi.com:8080 --data=~/sites/myApp/testData

By default the vcr looks for a sibling if it can't find a requested object. If you ask for user/7, for example, it will return user/42 if it has one. This is awesome if you just want to keep working and it doesn't matter too much that it's the wrong user/product/sprocket/whatever.

Not everyone wants this behavior though. To turn it off:

api-vcr http://myapi.com:8080 --noSiblings

Seeding data

Data is all in the ./api-vcr-data folder local to where you run the command.

This is configurable, so you can store your data files with your project if you want to.

Folder and file names are used to determine the api path the VCR playback should respond to. If you'd like the server to respond to users/1, create this file:

./users/1.json

You can record and modify, or seed from scratch, a complex tree of test data and distribute it in git with your project for consistent testing across machines.

Developing

Running the local version is the same except instead of api-vcr, you use ./cli.js from this folder.

You can bump the version with npm's awesome npm version patch && npm publish.

TODO

  • [x] Start the app a record option

  • [x] Logs all requests to console

  • [x] Pass requests on to the recorded server

  • [x] Create a directory structure that matches requests (namespace by server and port to support multiple APIs)

  • [x] Store request responses as JSON files

  • [x] Support missing objects (eg: if you have recorded surfboard/3 and they request 5, return 3 instead)

  • [x] Print version on startup

  • [x] Switch to a global install for easier run API by packages that depend on this one.

  • [ ] Bug: encode colons to %3A or something else in filenames

  • [ ] Bug: returning similar siblings returns deep nested JSON if there is a child folder (eg: posts/777 returns posts/1/comments.json)

  • [ ] Bug: returning siblings shouldn't return list objects for id requests and visa-versa

  • [ ] Support a config file, maybe in ./api-vcr-config.json (is there an option parsing library that supports fall-through from args to json file to defaults?)

  • [ ] Print the fully resolved path name for data, otherwise it's unclear where . is

  • [ ] Have a simple index page with list of all routes we know about, for easy debugging/transparency

  • [ ] Support query params

  • [ ] Option to trim large array responses to 20-100 max (default true)

  • [ ] Support response types other than JSON gracefully

  • [ ] Support POST, PUT, DELETE (at least don't error, and return a sensible object)