Note: This documentation is for version 1 of the Now platform. For the latest features, please see the version 2 documentation. If you have yet to upgrade, see the upgrade guide.

Building a Basic JSON API

Nowadays, every properly built application requires at least one API endpoint where it can load data from.

There are various ways to build one of these APIs. But for this example, I'm going to show you the most effective one using a tiny tool named micro, which we built specifically for this purpose.


Before diving into building the microservice, please make sure that your instance of Node is up-to-date (at least version 6). Assuming that it's the case, continue with creating a directory and switch to it. Run this in your terminal:

mkdir json-api && cd json-api

Now let's create the project's files inside that directory. Start over with creating a package.json:

  "version": 1,
  "name": "json-api",
  "scripts": {
    "start": "micro"
  "dependencies": {
    "micro": "latest"

As you can see, this file now contains three properties:

  • name tells Now the name of the deployment
  • scripts will make the micro command run when starting the deployment
  • dependencies tells Node.js to download the latest version micro

Next, install micro (the only dependency) by running npm's install command:

npm install

Creating the Service

Once the command has finished running, you'll see a directory named node_modules containing your dependencies. Now that you've installed everything required, you can populate the source files with code.

By default, micro will expect an index.js file to exist in your project's directory. However, if you want to run a different file, that's also possible. But for this example, we'll go with the default behavior:

module.exports = () => ({
  date: new Date

The exported arrow function shown above simply returns an object with the current date. And thanks to micro providing the functionality of a web server, you only need to run the start script contained within your package.json file:

npm start

BOOM! The service will start running and you'll see a message like this one showing that micro started exposing the code you wrote on the default port 3000:

> Ready! Listening on

Go to the URL returned ( and you should see something like this:

Retrieving and Sending Data

That's great, isn't it? But we're not quite there yet! The next step is to take advantage of async and await by loading real data once the request comes in (then we'll send it back as the response).

As an example, we're going to retrieve the list of public members inside our GitHub organization using their API.

In order to get there, the first thing we need to do is install node-fetch, a package that allows us to easily load data from an API endpoint and now that we already have a package.json in place, this only requires a command:

npm install --save node-fetch

You'll notice that the package got added to your dependencies list. We achieved this by taking advantage of the --save option. Now the property should look similar to this:

"dependencies": {
  "micro": "latest",
  "node-fetch": "^1.6.3"

Done? Perfect! Then let's get over to updating index.js. First, we need to load node-fetch:

const fetch = require('node-fetch')

Next, prepend the new async keyword (which allows us to run asynchronous code inside it) to the exported function, use fetch() with GitHub's endpoint URL, assign it to a constant and then parse the JSON in the response using the .json() method.

Once that's done, you only need to return the parsed JSON data. All in all, it should look like this:

module.exports = async () => {
  const request = await fetch('')
  const data = await request.json()

  return data

Now save the file and run it the service again (if it's still running, stop it using ctrl + c before starting it again):

npm start

Assuming that you've followed this post to this point, you should now see able to open in your browser and see a list of all public members of the ZEIT organization on GitHub:

Deploying the Service

Now that the JSON API works locally, we can deploy it by running this command:


Once Now has finished uploading the files, you'll see a URL that points to your API microservice. This means that you can already use this URL in a testing application and load the data into it.

But in the case of a real microservice, you would now have to assign an alias to it.