Accessing the REST API

Table of Contents

• The Emulator's REST API
• Creating a client
  • Installing the Google APIs Node.js Client
  • Creating a client for the Emulator's REST API
  • Creating a client the production Google Cloud Functions REST API
• Making requests
  • Creating a function
  • Listing functions
  • Calling a function
  • Getting a function
  • Deleting a function

The Emulator's REST API

The Emulator implements the Google Cloud Functions REST API as defined in https://cloudfunctions.googleapis.com/$discovery/rest?version=v1beta2. The Emulator exposes its own REST discovery document at http://REST_HOST:REST_PORT/$discovery/rest?version=v1beta2.

When the Emulator starts, its REST API listens on the host and port as configured in the restHost and restPort settings, which default to localhost and 8008, respectively. You can see the hostname on which the Emulator's REST API is listening by running:

functions status

which should print an entry like this:

├────────────────┼───────────────────────────┤
│ REST Service   │ http://localhost:8008/    │
├────────────────┼───────────────────────────┤

With the REST API listening on http://localhost:8008/ then the Emulator's REST discovery document would be available at http://localhost:8008/$discovery/rest?version=v1beta2.

Creating a client

Just as the Google APIs Node.js Client can be used to communicate with the production Google Cloud Functions REST API, it can be used to communicate with the Emulator's REST API.

Installing the Google APIs Node.js Client

Install the googleapis package:

npm install --save googleapis

Creating a client for the Emulator's REST API

Create a client for the Emulator's REST API:

const google = require('googleapis');
// Adjust localhost:8008 to match the host and port where your Emulator is running
const DISCOVERY_URL = 'http://localhost:8008/$discovery/rest?version=v1beta2';

function buildService (callback) {
  google.discoverAPI(DISCOVERY_URL, (err, functionsService) => {
    if (err) {
      callback(err);
      return;
    }

    callback(null, functionsService);
  });
}

Creating a client for the production Google Cloud Functions REST API

Create a client for the production Cloud Functions REST API:

const google = require('googleapis');
const DISCOVERY_URL = 'https://cloudfunctions.googleapis.com/$discovery/rest?version=v1beta2';

function buildService (callback) {
  // Obtain credentials. This requires the following environment variables:
  //   - GCLOUD_PROJECT
  //   - GOOGLE_APPLICATION_CREDENTIALS
  google.auth.getApplicationDefault((err, authClient) => {
    if (err) {
      callback(err);
      return;
    }

    if (authClient.createScopedRequired && authClient.createScopedRequired()) {
      authClient = authClient.createScoped([
        'https://www.googleapis.com/auth/cloud-platform'
      ]);
    }

    const options = {
      // Supply the credentials to the new service
      auth: authClient
    };

    google.discoverAPI(DISCOVERY_URL, options, (err, functionsService) => {
      if (err) {
        callback(err);
        return;
      }

      callback(null, functionsService);
    });
  });
}

Making requests

Creating a function

The following creates an HTTP function named helloWorld:

functionsService.projects.locations.functions.create({
  location: 'projects/YOUR_PROJECT_ID/locations/us-central1',
  resource: {
    name: 'projects/YOUR_PROJECT_ID/locations/us-central1/functions/helloWorld',
    // The zip file containing the function code
    sourceArchiveUrl: 'gs://YOUR_STAGE_BUCKET/some-file.zip',
    // This marks the functions as an HTTP function
    httpsTrigger: {}
  }
}, (err, operation) => {
  function pollOperation () {
    functionsClient.operations.get({
      auth: authClient,
      name: operation.name
    }, (err, _operation) => {
      if (err) {
        throw err;
      } else if (_operation.done) {
        console.log(_operation);
      } else {
        process.stdout.write('.');
        setTimeout(() => pollOperation(), 2000);
      }
    });
  }

  // Start polling
  pollOperation();
});

Listing functions

The following lists deployed functions:

functionsService.projects.locations.functions.list({
  location: 'projects/YOUR_PROJECT_ID/locations/us-central1'
}, (err, result) => {
  console.log(err, result);
});

Calling a function

The following calls a function named helloWorld and sends it some JSON data:

functionsService.projects.locations.functions.call({
  name: 'projects/YOUR_PROJECT_ID/locations/us-central1/functions/helloWorld',
  resource: {
    // Customize the object as desired
    data: {
      foo: 'bar'
    }
  }
}, (err, result) => {
  console.log(err, result);
});

Getting a function

The following gets a function named helloWorld:

functionsService.projects.locations.functions.get({
  name: 'projects/YOUR_PROJECT_ID/locations/us-central1/functions/helloWorld'
}, (err, result) => {
  console.log(err, result);
});

Deleting a function

The following deletes a function named helloWorld:

functionsService.projects.locations.functions.delete({
  name: 'projects/YOUR_PROJECT_ID/locations/us-central1/functions/helloWorld'
}, (err, result) => {
  console.log(err, result);
});