vobu / sap-cf-destination

convenience module for querying a destination via a connectivity instance on SAP BTP Cloud Foundry

SAP BTP Cloud Foundry destination handler

Install

npm install --save sap-cf-destination

Prerequisites

• destination and destination instance created
• connectivity instance created
• xsuaa instance created
• all of the above instances bound to the node app, e.g. via manifest.yml:

  applications:
  - name: my_app
    path: my_app
    memory: 128M
    services:
      - xsuaa-instance
      - connectivity-instance
      - destination-instance

Usage

const callDestination = require('sap-cf-destination');

// Promise chain
callDestination({
        url: '/api/json',
        connectivity_instance: 'connectivity-lite',
        uaa_instance: 'uaa-lite',
        destination_instance: 'destination-lite',
        destination_name: 'tbaas',
        http_verb: 'POST',
        payload: {
            "me": "here"
        }
    })
        .then(response => {
            // do sth clever from the response
            // of $server_behind_destination_'tbaas'/api/json
        })
        .catch(err => {
            // oh no 💩
        })
        
// async/await? 👏
// add the 'async' keyword to an outer function wrapping 'callDestination'
async function getIt() {
    try {
        const response = await callDestination({...});
        // do sth clever w/ the response
    } catch (err) {
        // oh no 💩
    }
}

API

sap-cf-destination(options) ⇒ Promise.<(any|never)>

Param	Type	Description
options	Map	configuration options for several CF service instances
options.url	string	the url to call in the destination, absolute path (including leading slash) e.g. /api/v1/json
options.connectivity_instance	string	name of the instance of the connectivity service
options.uaa_instance	string	name of the instance of the uaa service
options.destination_instance	string	name of the instance of the destination service
options.destination_name	string	name of the destination to use
options.http_verb	'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'	HTTP method to use
[options.payload]	object	payload for POST, PUT or PATCH
[options.formData]	object	mimic a browser for POSTing a form to the destination; implies http verb POST
[options.content_type]	string	value for "Content-Type" http header, e.g. "application/json"
[options.full_response]	boolean	whether to have the full response (including all headers etc) pass through to the caller (BE -> proxy -> client)
[options.tech_error_only]	boolean	get a rejection only if the request failed for technical reasons, so e.g. 404 is considered a valid response
[options.binary]	boolean	whether to expect (and deliver) a binary at @param url
[options.scc_name]	string	Location ID of the SAP Cloud Connector

Hints & Limitations

• all major HTTP verbs are supported (GET, POST, PUT,PATCH,HEAD, DELETE,OPTIONS) per se
  BUT: if the proxy software decides to not let any of them pass through, the request originating from this module will of course fail
• POST, PUT and PATCH only support a JSON payload. The payload itself can be a plain, deeply nested object; it will be stringified automatically
• POST now supports both a JSON payload and a form-style ("like a browser") submission:

  callDestination({
    url: ...,
    http_verb: 'POST',
    formData: {
      field1: "some value",
      field2: JSON.stringify([ { "el1": "v1", "el2": "v2" } ])  // stringify deep nested objects and array structures
    }
  })

• use scc_name: '<locID>' as a parameter to specify location ID of the SAP Cloud Connector (default: none)

  callDestination({
          //...
          scc_name: '<locID of SCC>'
      }).then(...).catch(...);

• use full_response: true as a parameter to obtain the full response payload, e.g. to get access to response headers

  callDestination({
          //...
          full_response: true
      }).then(...).catch(...);

• use tech_error_only: true as a parameter to only get a rejection if the request failed for technial reasons ("as long as it has a status code, it's a valid response")

  callDestination({
          //...
          tech_error_only: true
      }).then( response => {
          // even ☕️ ends up here
          // add
          //    full_response: true (see above)
          // to get response.statusCode
      }).catch( err => {
          // network layer problem or such
      });

• do a download of a binary file by specifying the matching Content-Type of the file and setting binary to true;
  this will deliver a Buffer useable in writeStreams

  callDestination({
          //...
          content_type: 'application/zip',
          binary: true
      }).then( buffer => {
          // write Buffer
          fs.createWriteStream('file.zip')
            .write(buffer, 'binary')
            .end();
          // don't forget to listen to the error and finish event
          // ...
      }).catch(...);

License

Apache License 2.0

References

• code inspiration from https://github.com/bertdeterd/scc-connector
• ported Java reference code from https://help.sap.com/viewer/cca91383641e40ffbe03bdc78f00f681/Cloud/en-US/313b215066a8400db461b311e01bd99b.html

sap-cf-destination's Issues

Feature Request

Sometimes it's very useful to get all informations (like, url, type etc..) of a destination.
These infos are already used to call the destination, but not exposed.

I would like to suggest that these informations can be retrieved.

No Authentication in Backend Destination

Hi,

Currently is is referring to the "Basic Authentication" credentials maintained in the SAP backend in the Destination service. Basically, whatever the API/OData from the backend destination is exposed to cloud, there's no prompt for backend authorization, anyone can access to the data.

Is there plan to add Basic Authentication check if username and password is not added to the CF Destination cockpit?