|
| 1 | +# Writing REST Service Event Handlers |
| 2 | + |
| 3 | +## Table of contents |
| 4 | +- [Introduction](#introduction) |
| 5 | +- [REST Service Handler Structure](#structure) |
| 6 | + - [Using Javascript](#js) |
| 7 | + - [Using Typescript](#ts) |
| 8 | +- [Writing REST Service Handler Functions](#writing) |
| 9 | +- [Supported Events](#events) |
| 10 | + |
| 11 | +## Introduction <a name="introduction"> |
| 12 | + |
| 13 | +A REST Service Event Handler (RSEH) enables you to transform customize the REST request body before the REST call is made, and to transform the response body after the REST call is made. |
| 14 | + |
| 15 | +<br/><br/> |
| 16 | +The RSEH is deployed as part of a component service. The built-in Call REST component checks whether an event handler is registered |
| 17 | +and if so, the component invokes the event handler methods to transform the request and/or response body. |
| 18 | + |
| 19 | +## RESTService Event Handler Structure <a name="structure"> |
| 20 | + |
| 21 | +### Using Javascript <a name="js"> |
| 22 | + |
| 23 | +A REST service event handler exports two objects: the `metadata` object that provides the name of the component and the `eventHandlerType` (which should be set to `RestService`), and the `handlers` object that contains the event handler functions. |
| 24 | + |
| 25 | +```javascript |
| 26 | +module.exports = { |
| 27 | + metadata: { |
| 28 | + name: 'myRestServiceEventHandler', |
| 29 | + eventHandlerType: 'RestService' |
| 30 | + }, |
| 31 | + handlers: { |
| 32 | + |
| 33 | + /** |
| 34 | + * Handler to transform the request payload |
| 35 | + * @param {TransformPayloadEvent} event |
| 36 | + * @param {RestServiceContext} context |
| 37 | + * @returns {object} the transformed request payload |
| 38 | + */ |
| 39 | + transformRequestPayload: async (event, context) => { |
| 40 | + return event.payload; |
| 41 | + }, |
| 42 | + |
| 43 | + /** |
| 44 | + * Handler to transform the response payload |
| 45 | + * @param {TransformPayloadEvent} event |
| 46 | + * @param {RestServiceContext} context |
| 47 | + * @returns {object} the transformed response payload |
| 48 | + */ |
| 49 | + transformResponsePayload: async (event, context) => { |
| 50 | + return event.payload; |
| 51 | + } |
| 52 | + } |
| 53 | +}; |
| 54 | +``` |
| 55 | + |
| 56 | +If needed, you can define the `metadata` and `handlers` members as functions rather than as an objects. |
| 57 | + |
| 58 | +### Using TypeScript <a name="ts"> |
| 59 | + |
| 60 | +In TypeScript, the event handler class implements the `RestServiceEventHandler` interface. This interface requires both of the following methods: |
| 61 | + |
| 62 | +- The `metadata` method that returns an object of type `RestServiceEventHandlerMetadata`. |
| 63 | +- The `handlers` method that returns an object of type `RestServiceEventHandlers`. |
| 64 | + |
| 65 | +```typescript |
| 66 | +import { RestServiceContext, RestServiceEventHandler, RestServiceEventHandlers, RestServiceEventHandlerMetadata, TransformPayloadEvent } from '@oracle/bots-node-sdk/lib'; |
| 67 | + |
| 68 | +export class MyRestServiceEventHandler implements RestServiceEventHandler { |
| 69 | + |
| 70 | + public metadata(): RestServiceEventHandlerMetadata { |
| 71 | + return { |
| 72 | + name: 'myRestServiceEventHandler', |
| 73 | + eventHandlerType: 'RestService' |
| 74 | + }; |
| 75 | + } |
| 76 | + |
| 77 | + public handlers(): RestServiceEventHandlers { |
| 78 | + return { |
| 79 | + |
| 80 | + /** |
| 81 | + * Handler to transform the request payload |
| 82 | + * @param {TransformPayloadEvent} event |
| 83 | + * @param {RestServiceContext} context |
| 84 | + * @returns {object} the transformed request payload |
| 85 | + */ |
| 86 | + transformRequestPayload: async (event: TransformPayloadEvent, context: RestServiceContext): Promise<any> => { |
| 87 | + return event.payload; |
| 88 | + }, |
| 89 | + |
| 90 | + /** |
| 91 | + * Handler to transform the response payload |
| 92 | + * @param {TransformPayloadEvent} event |
| 93 | + * @param {RestServiceContext} context |
| 94 | + * @returns {object} the transformed response payload |
| 95 | + */ |
| 96 | + transformResponsePayload: async (event: TransformPayloadEvent, context: RestServiceContext): Promise<any> => { |
| 97 | + return event.payload; |
| 98 | + } |
| 99 | + |
| 100 | + }; |
| 101 | + } |
| 102 | + |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | +## Writing Event Handler Functions <a name="writing"> |
| 107 | + |
| 108 | +The first argument of each event method is the `event` object. The properties available in this object depend on the type of event. |
| 109 | +See the [list of supported entity events](#events) for information on which properties are available with which event. |
| 110 | + |
| 111 | +The second argument of each event method is the `context` object. This object references the [RestServiceContext](https://oracle.github.io/bots-node-sdk/RestServiceContext.html) that provides access to convenience methods you can use to create your event handler logic. |
| 112 | + |
| 113 | +<b>TIP</b>: if you are using a JavaScript IDE like Visual Studio Code, you can get code insight and code completion support by defining the types used in the event handlers as follows in your JavaScript handler file: |
| 114 | +```javascript |
| 115 | +const { RestServiceContext, RestServiceEventHandler, RestServiceEventHandlers, RestServiceEventHandlerMetadata, TransformPayloadEvent } = require ('@oracle/bots-node-sdk/lib'); |
| 116 | +``` |
| 117 | +When using TypeScript, you will automatically get code completion support if your IDE supports it. |
| 118 | + |
| 119 | +## Supported Events <a name="events"> |
| 120 | + |
| 121 | +The table below lists the event methods that can be implemented: |
| 122 | + |
| 123 | +| Event | Description | Event Properties | |
| 124 | +|--|--|--| |
| 125 | +| `transformRequestPayload` | A handler that can be used to trasnform the REST request body. | <ul><li><b>payload</b>: The request body object.</li></ul> |
| 126 | +| `transformResponsePayload` | A handler that can be used to trasnform the REST response body. | <ul><li><b>payload</b>: The response body object.</li></ul> |
| 127 | + |
0 commit comments