BaaS Introduction

This documentation will walk you through creating API connectors for a mock user management API.

ServisBOT mock user API

https://7i8ohktmel.execute-api.eu-west-1.amazonaws.com/prod/

Our API has the following definition:

users/
    GET  #Example for query parameters
users/{userId}
    GET  #Get User identified in URL
    PUT  #Update User data

Get User Info via API connector

Our API expects userId in the url in order to return a user’s information.

  • We will call our API servisbotGetUser
  • the endpoint will be our url with a parameter instead of the userId https://7i8ohktmel.execute-api.eu-west-1.amazonaws.com/prod/user/${userId}
  • In order for our bot to set that parameter, we will create a RequestMapping for userId of type requestURL with the requestParameter set to the variable name we put in the endpoint.
  • Method is GET

servisbotGetUser.baas.json should look like:

{
  "Method": "GET",
  "Endpoint": "https://7i8ohktmel.execute-api.eu-west-1.amazonaws.com/prod/user/${userId}",
  "Headers": {},
  "Alias": "ServisbotGetUser",
  "Type": "api-connector",
  "RequestMapping": {
    "userId": {
      "type": "requestURL",
      "inputPath": "$.userId",
      "requestParameter": "userId"
      }
  },
  "ResponseMapping": {},
  "Body": {}
}

Test Your Connector

Testing this BaaS can be done using the baas execute --debug command

First create an execution file. Since we only have one RequestMapping the file can be composed of simply:

  • the Alias of the endpoint to be called
  • The RequestMapping set to 123456. Our mock API will fail unless the userId is 123456

servisbotGetUser.execute.json

{
  "Alias": "servisbotGetUser",
  "userId": "123456"
}

Run the command to execute the BaaS

sb-cli baas execute servisboGetUser.execute.json

Expected Response

{
  "response": {
    "user": "123456",
    "address": {
      "primaryAddress": "400 Westworld Drive",
      "postalzip": "90002",
      "stateprovince": "CA"
    },
    "products": [
      "5 Day Experience Package",
      "Premium Views"
    ],
    "status": "active",
    "email": "william@delosincorporated.com",
    "phone": "111-111-1111"
  },
  "statusCode": 200,
  "headers": {}
}

Create A User API connector

The mock endpoint can also emulate creating a user using a post request. This API connector will be more complex since the entire payload will need to be

{
  "address": {
    "primaryAddress": "400 Westworld Drive",
    "postalzip": "90002",
    "stateprovince": "CA"
  },
  "products": ["5 Day Experience Package", "Premium Views"],
  "status": "active",
  "email": "william@delosinc.com",
  "phone": "111-111-1111"
}

Building BaaS Definition

  • We will call our API servisbotCreateUser
  • The endpoint will not have any parameters: https://7i8ohktmel.execute-api.eu-west-1.amazonaws.com/prod/user
  • We will assume that all created users will be in the active state and will set that property statically in the definition. A value will be added to the definition’s body object.
  • The rest of the payload’s properties will be set by ‘requestParameters’
  • Some of the properties will be nested within each other, and be of type requestBody since they are included as part of the requests body. Those properties will also need to have requestBodyPath, instead of requestParameter
  • Method is POST

servisbotCreateUser.baas.json

{
  "Method": "POST",
  "Endpoint": "https://7i8ohktmel.execute-api.eu-west-1.amazonaws.com/prod/user",
  "Headers": {},
  "Alias": "servisbotCreateUser",
  "Organization": "trollin",
  "Updated": 1568230227450,
  "RequestMapping": {
    "phone": {
     "type": "requestBody",
     "requestBodyPath": "$.phone",
     "inputPath": "$.phone"
   },
   "email": {
     "type": "requestBody",
     "requestBodyPath": "$.email",
     "inputPath": "$.email"
   },
   "products": {
     "type": "requestBody",
     "requestBodyPath": "$.products",
     "inputPath": "$.products"
   },
   "primaryAddress" : {
     "type": "requestBody",
     "inputPath": "$.primaryAddress",
     "requestBodyPath": "$.address.primaryAddress"
   },
   "postalzip" : {
     "type": "requestBody",
     "inputPath": "$.postalzip",
     "requestBodyPath": "$.address.postalzip"
   },
   "stateprovince" : {
     "type": "requestBody",
     "inputPath": "$.stateprovince",
     "requestBodyPath": "$.address.stateprovince"
   }
  },
  "ResponseMapping": {},
  "Type": "api-connector",
  "Body": {
    "status": "active"
  }
}

Test Your Connector

Testing this BaaS can be done using the baas execute --debug command

First create an execution file. The request mapping will have to match the inputPath of the ResponseMapping objects.

  • The Alias of the endpoint to be called
  • The RequestMapping for our values

servisbotCreateUser.execute.json

{
  "Alias": "servisbotCreateUser",
  "email": "dolores@delosinc.com",
  "phone": "222-222-2222",
  "products": ["Some","products","purchased"],
  "primaryAddress": "400 Westworld Drive",
  "postalzip": "90002",
  "stateprovince": "CA"
}

sb-cli baas execute servisbotCreateUser.execute.json --debug

Expected Response

{
  "response": {
    "statusCode": 200,
    "headers": {
      "x-custom-header": "my custom header value"
    },
    "body": {
      "status": "active",
      "address": {
        "primaryAddress": "400 Westworld Drive",
        "stateprovince": "CA",
        "postalzip": "90002"
      },
      "phone": "222-222-2222",
      "email": "dolores@delosinc.com",
      "products": [
        "Some",
        "products",
        "purchased"
      ],
      "userId": "123457"
    }
  },
  "statusCode": 200,
  "headers": {}
}

Using Response Mappings

Just like it is possible to map one data input format into a different object when calling an API using RequestMappings, it is also possible to return only specific data from an API response using ‘ResponseMapping’s.

It is relatively easy to take our existing Create BaaS and adjust it to work with the update user PUT method.

  • Endpoint will need the userId requestURL token in it since we are updating a specific user.
  • The RequestMapping definition will have a combination of ‘requestURL’ and requestBody objects.
  • Method should be PUT.
  • A ResponseMapping is set for the phone and userId properties. This means that the resulting response will only give us the phone and user fields.

servisbotUpdateUser.baas.json

{
  "Headers": {},
  "Method": "PUT",
  "Endpoint": "https://7i8ohktmel.execute-api.eu-west-1.amazonaws.com/prod/user/${userId}",
  "Alias": "servisbotUpdateUser",
  "Type": "api-connector",
  "RequestMapping": {
    "userId": {
      "type": "requestURL",
      "inputPath": "$.userId",
      "requestParameter": "userId"
      },
    "email": {
      "type": "requestBody",
      "inputPath": "$.email",
      "requestBodyPath": "email"
    },
    "phone": {
      "type": "requestBody",
      "inputPath": "$.phone",
      "requestBodyPath": "phone"
    },
    "products": {
      "type": "requestBody",
      "inputPath": "$.products",
      "requestBodyPath": "$.products"
    },
    "primaryAddress" : {
      "type": "requestBody",
      "inputPath": "primaryAddress",
      "requestBodyPath": "$.address.primaryAddress"
    },
    "postalzip" : {
      "type": "requestBody",
      "inputPath": "postalzip",
      "requestBodyPath": "$.address.postalzip"
    },
    "stateprovince" : {
      "type": "requestBody",
      "inputPath": "stateprovince",
      "requestBodyPath": "$.address.stateprovince"
    }
  },
  "ResponseMapping": {
    "phone": {
      "outputPath": "$.phone",
      "responseBodyPath": "$.phone",
      "type": "responseBody"
    },
    "userId": {
      "outputPath": "$.userId",
      "responseBodyPath": "$.userId",
      "type": "responseBody"
    }
  },
  "Body": {
    "status": "active"
  }
}

Test Your Connector

Testing this BaaS can be done using the baas execute --debug command

First create an execution file. The request mapping will have to match the inputPath of the ResponseMapping objects.

  • the Alias of the endpoint to be called
  • The RequestMapping for our values

servisbotUpdateUser.execute.json

{
  "Alias": "servisbotCreateUser",
  "email": "dolores@delosinc.com",
  "phone": "222-222-2222",
  "products": ["Some","products","purchased"],
  "primaryAddress": "400 Westworld Drive",
  "postalzip": "90002",
  "stateprovince": "CA"
}

sb-cli baas execute servisbotUpdateUser.execute.json --debug

Expected Response