Calling external REST Service from AWS Lambda? (Part 2)

tiny, simple, and without any overhead in Packaging.

After Part 1, here now part in Part 2.

Still no need for request.js, Axios, or deep-dive into Node.js HTTP.

Photo by Jörg Grote on Unsplash

In this article, I like to give a little overview of some more benefits and hints

• usage of OAuth Bearer Tokens
• REST Method and Uri
• Datatypes
• usage of URL Parameter
• Body payloads
• Request validation, and usage of ‘shapes’
• Response validation, and how to avoid issues
• change Endpoint on the fly

usage of OAuth Bearer Tokens

as a sample, I use here a TIBCO Cloud Service to create a new TIBCO Cloud Live Apps Case Instance in the Case Management System.

As you can see this Service requires to use of a Bearer Token to perform the request against TIBCO Cloud.

The Token can get generated here:

TIBCO Cloud — Settings — OAuth access token generation

Note: Sign up for a 30-Day Free Trial of TIBCO Cloud Integration

In AWS Lambda the API can get called like here using pure AWS SDK Core functionalities:

This Sample shows smoothly how to use OAuth, REST Type, URI definition, Input Interface handling, including validation, and how to handle the Response Data to return the newly created Case InstanceID “caseReference”

REST Method and Uri

in the example, you find the REST operation Method specified here inside the apiConfig section, directly followed by the URI

http: {
         method: 'POST',
         requestUri: '/process/v1/processes'
}

The AWS SDK support all kind of Methods, e.g. GET, POST, PATCH, PUT, DELETE, etc.

Datatypes

List of supported Datatypes, to be used in Operation definitions

'string'
'integer'
'float'
'boolean'
'timestamp'
'structure'
'list'
'map'
'base64'
'binary'

usage of URI parameter

URI parameter con be defined like here, under members the location attribute defines that the parameter has to be replaced in the URI.

http: {
        method: 'GET',
        requestUri: '/item/{id}'
}

Input members section

members: {
       'Id': {
       // all kinds of validators are available
       type: 'string',
       // include it in the call URI
       location: 'uri',
       // this is the name of the placeholder in the URI
       locationName: 'Id'
}

Body payloads

to send a JSON payload as a request body, an Input payload can be defined

payload: 'body',

the body can then get defined e.g. as structure together with some members

'body': {
         type: 'structure',
         required: [ 'id', 'fname', 'lname' ],
         members: {
                    'id': {
                       type: 'integer'
                    },
                    'fname': {},
                    'lname': {}
                  }
         }

Request validation, and usage of ‘shapes’

All requests get validated for required fields and datatypes before the request is sent.

The Concept of shapes is very useful if you have a reoccurring data structure,
of you need to define complex structures for request.

apiConfig: {
        metadata: {
            protocol: 'rest-json' // API is JSON-based
        },
        operations: {
            complexPost: {
                http: {
                    method: 'POST',
                    requestUri: '/v1/complexPost'
                },
                input: {
                    "shape": "complexPostRequest"
                }
            }
        },
        'shapes': {
            'complexPostRequest': {
                type: 'structure',
                required: [ 'auth' ],
                payload: 'body',
                members: {
                   ...

Shapes can be used in operations as part of the input, and shapes and be even used within other shapes. Like here for ‘shape’: ‘recipient’

members: {
       'recipients': { 
             type: 'list', member: { 'shape': 'recipient'} 
    } 
   }
  }
 }
}, // <- back main shapes level
'recipient': {
     "type": "string"
}

Response validation, and how to avoid issues

Even Response validation can be used, but this means even Response Types need to get defined for each Operation.

In some cases, you may like to get only a subset of the data coming from the REST service, so you can just disable Response parsing by using.

const service = new AWS.Service({
    // the API base URL
    endpoint: <url>,
    // don't parse all API responses
    convertResponseTypes: false,

Note: this can also help to avoid versioning issues, as you may just rely on basic details of the underlying service.

REST service that returns none JSON

some services don’t return a valid JSON e.g. just an ID as result, but AWS-SDK always tries to return a data object.

Here a workaround that returns again a valid JSON from the Response body.

The “.on(‘success’)” workaround and returning the “httpResponse.body” does the trick perfectly!

Change Endpoint on the fly

Sometimes it’s necessary to adjust the endpoint URL because e.g. a different region needs to get selected. You can do this by just re-configuring the AWS SDK Service Endpoint Object on the fly, before calling the service.

var region="eu.";
service.endpoint.host=region+"example.com";
service.endpoint.hostname=region+"example.com";
service.endpoint.href="https://"+region+"example.com/";
       
service.getSomething({
...

TIBCO LABS

this article was written under the TIBCO LABS initiative, full reusable source can be found under the public TIBCO LABS GitHub Repository
incl. BSD 3-Clause License.

What’s next

This was just a follow-up, working currently on some more content
— stay tuned!

Thanks for reading and claps!