Create a Google Apps Script SDK from any JSON RESTful API.
There is never a Google Apps Script SDK made available for the best APIs out there. It's time to start changing that, hence this library that allows to build an SDK out of any JSON-based RESTful API.
A detailed article with examples can be found in my story on Medium.
Option 1: clone this repo into your project and bundle it into your GAS project
Option 2: Copy the already-bundled APIWrapper.js
file into your project.
function mySDK() {
return new APIWrapperBuilder(`<<base url>>`, <<authentication object>>)
.addMethod('methodNameOne', <<method options>>)
.addMethod('methodNameTwo', <<method options>>)
.build();
}
function execute() {
mySDK().methodNameOne(<<argsObj>);
}
- Create an instance of
API Wrapper Builder
providing a base URL (must not contain a slash at the end) and authentication options - Use method chaining to define your methods
- The library uses the Builder pattern, it requires the the
APIWrapperBuilder
instance to use thebuild()
method in the end to convertg it the theAPIWrapper
class.
GAS API Wrapper supports three types of authentication:
- Token with or without a secret as part of the query string or header.
- Basic authentication.
- Bearer authentication.
const apiWrapperBuilder =
new APIWrapperBuilder(<<base url>>, {
type: 'KeyToken',
addTo: 'query',
token: { name: '<<token name>>', value: '<<token value>>' },
secret: { name: '<<secret name>>', value: '<<secret value>>' },
});
The Token authentication, named KeyToken
in the library, suppors the following options:
addTo
(required): supports two values:query
orheaders
depending on where the API requires you to add the token, the query string or headers respectivelytoken
(required): an object that contains 2 values, the token name and its value; for example{name: 'token', value='qwerty'}
in a query string will be evaluated totoken=qwerty
secret
(optional): some APIs also require a secret to be added together with the token; the syntax works in the same way as the token.
const apiWrapperBuilder =
new APIWrapperBuilder(<<base url>>, {
type: 'Basic',
username: '<<user name>>',
password: '<<password>>',
})
To use Basic authorization, set type to Basic
and supply a user name and a password in the auth options.
const apiWrapperBuilder =
new APIWrapperBuilder(<<base url>>,
{
type: 'Bearer',
token: '<<Bearer token>>',
}
)
To use Bearer authorization, set type to 'Bearer' and supply the Bearer
token in the auth options.
The custom methods are defined with the addMethod()
method, that takes a method name and options arguments.
apiWrapperBuilder
.addMethod('addUser', {
method: 'POST',
path: '/users',
payload: {
name: 'John',
age: 33,
},
headers: {
'Content-Type': 'application/json',
},
queryParams: {
key: 'value',
},
})
.build();
Method name must be a string.
The options
object takes the following entries:
method
: required HTTP method, typicallyGET
,POST
,PUT
orDELETE
path
: the endpoint you are queryingpayload
: the payload objectheaders
: the headers objectqueryParams
: the key-value pair object that is transformed into a query string
Dynamic values can be used in the path
, payload
or queryParam
entries with mustache notation:
const methodOptions = {
method: 'PUT',
path: '/users/{{userId}}',
payload: {
name: '{{userName}}',
},
queryParams: {
metaData: '{{metaData}}',
},
};
A method defined with such optioins can be called like so:
mySDK().myMethod({
userId: 'xxx',
name: 'Jane',
metdaData: 'yyy',
});
All dynamic values are optional and the entries are removed from the requrest if not used.
If you would like to contribute, I am looking for help in the following areas.
Find any edge-cases that dont't work and help me solve them.
Create SDKs with this library and add them to this README.
0.1.0