gcp-api-client

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:

Property	Description
baseUrl	OPTIONAL - String; default value is https://www.googleapis.com
scopes	OPTIONAL - String or array of strings; must be appropriate for the service endpoint that is intended to be called; default value is https://www.googleapis.com/auth/cloud-platform
pathParams	OPTIONAL - Object; each key/value pair represents a path parameter and its replacement string (see details below)

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

client.post(path[, options][, callback])

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:

Property	Description
query	OPTIONAL - Object; if present, a query string is generated with the specified keys and values
json	OPTIONAL - Object to be serialized into JSON body
form	OPTIONAL - Object to be serialized into URL-encoded body
text	OPTIONAL - String to be used as request body
file	OPTIONAL - String; path to the file to be uploaded
type	OPTIONAL - String; relevant only if file is present; MIME type of the file to be uploaded; may be omitted if file includes an extension that indicates the actual MIME type
headers	OPTIONAL - Object; headers to be added to the request; there is no need to specify the accept header or the content-type header since they are automatically generated

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

json	form	text	file
x				The content-type header is set to application/json and the json object is used as body after serialization
	x			The content-type header is set to application/x-www-form-urlencoded and the form object is used as body after serialization
		x		The content-type header is set to text/plain and the text string is used as body
			x	The content-type header is set to the value specified by type or derived from the extension of file if type is omitted; the content of file is streamed as body
x		x		The content-type header is set to multipart/related; the first part has application/json body; the second part has text/plain body
x			x	The content-type header is set to multipart/related; the first part has application/json body; the second part has content type set to the value specified by type or derived from the extension of file if type is omitted

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][, callback])

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

client.put(path[, options][, callback])

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

client.patch(path[, options][, callback])

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

client.delete(path[, options][, callback])

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.