gcp-api-client v1.1.0

gcp-api-client

REST API client for Google Cloud Platform services. Not a replacement for the client libraries available from Google.

This package merely exposes some of the functionalities of the @google-cloud/common package to facilitate the use for simple API requests.

If you want to use this client from a local shell, you must have the Google Cloud SDK installed to enable authentication. Refer to the gcloud auth documentation for info on how to managed OAuth2 credentials.

Overview

const apiClient = require('gcp-api-client');

const client =  apiClient({
  baseUrl: 'https://cloudfunctions.googleapis.com',
  scopes: 'https://www.googleapis.com/auth/cloudfunctions'
});

client.get('/v1/projects/{{projectId}}/locations/-/functions', (error, response) => {
  // Process response
});

All the request methods can either be invoked with callbacks (as in the example above) or return promises:

client.get('/v1/projects/{{projectId}}/locations/-/functions').then(processResponse);

async function makeRequest() {
  let response = await client.get('/v1/projects/{{projectId}}/locations/-/functions');
}

Once instantiated, the client can be used for multiple subsequent requests:

const client = require('gcp-api-client')();

async function makeRequests() {
  let response1 = await client.get('/storage/v1/b/my-bucket/o');

  let data = {
    query: { uploadType: 'multipart' },
    json: { name: 'my-object' },
    file: './picture.jpg'
  };

  let response2 = await client.post('/upload/storage/v1/b/my-bucket/o', data);
}

Installation

npm install gcp-api-client --save

Usage

The API client is instantiated as follows:

const apiClient = require('gcp-api-client');

const client = apiClient(options);

If present, options must be an object with following properties:

Once the API client has been instantiated, requests are made through the following methods:

client.post(path, options)

Initiates a POST request. path specifies the request path (relative to the baseUrl configured for the client). Must be a string starting with /. May contain parameters marked with double braces (see details below).

If present, callback must be a function that expects (error, response) as input parameters. Otherwise, if callback is not present, then client.post() returns a promise to resolve response or to catch error.

If present, options must be an object with the following properties:

The following combinations of json, form, text and file are supported:

response is an object obtained by parsing the JSON response returned by the server.

Only API calls that return JSON body are supported.

client.get(path, options)

Same as client.post() above, but for GET requests. Body is never sent with GET requests.

client.put(path, options)

Same as client.post() above, but for PUT requests.

client.patch(path, options)

Same as client.post() above, but for PATCH requests.

client.delete(path, options)

Same as client.post() above, but for DELETE requests. Body is never sent with DELETE requests.

Use of path parameters

One or more path parameters can be specified when the client is instantiated. Example:

const apiClient = require('gcp-api-client');

const client =  apiClient({
  pathParams: { bucket: 'my-bucket', location: 'us' }
});

The specified parameters are automatically inserted in the request path when the client is used to initiate a request. Double braces are used to mark the parameters:

client.get('/storage/v1/b/{{bucket}}/o').then(processResponse);

The above request is equivalent to:

client.get('/storage/v1/b/my-bucket/o').then(processResponse);

The {{projectId}} parameter has a special treatment. It can be used in the request path even if not specified when the client is instantiated. When this is the case, {{projectId}} is replaced with the default project for the environment.

Limitations

Some of the error messages returned by the @google-cloud/common package are too succinct to be useful. For example, the absence of a mandatory request parameter may result in an error with just Required as message. In those cases, you may want to inspect the error.response object that contains the complete response returned by the server.