@postman/postman-sdk

About

This SDK instruments express app to capture http requests for auto-generating accurate postman live collections.

Installation

npm install @postman/postman-sdk

Supported Instrumentations

Instrumentation	Supported Version	SDK Version	Tested
Sails	>=1.5.3	>=0.1.6	✅
Express	>=4.18.2	>=0.1.6	✅
http(nodejs)	>=14	>=0.1.6	✅
Fastify*	>=3.0.0	>=0.1.8	✅

Please Note : While other frameworks/variations of these frameworks (express derivatives) might work with our SDK, but they have not been extensively tested and might lead to discrepancies in results. We recommend using the specified framework or version to ensure accurate and consistent outcomes.

Note for Fastify support - Starting the server with fastify-cli using fastify start is not supported.

Initializing the SDK

At the top of your app.js file, before app is initialized add this.

initialize({
  collectionId: 'postman-collection-id'
  apiKey: '<your-postman-api-key>'
});

Configuration

SDK's initialization can be configured with these values

• collectionId: Postman collectionId where requests will be added. This is the id for your live collection.

  • type: string

• apiKey: Postman api key needed for authentication.

  • type: string

• receiverBaseUrl: Where the data should be shipped to receiver's http endpoint.

  • type: string(valid url)

• bufferIntervalInMilliseconds: The interval in milliseconds that the SDK waits before sending data to Postman. The default interval is 5000 milliseconds. This interval can be tweaked for lower or higher throughput systems.

  • type: number
  • default: 5000

• enable: enable or disable the SDK. Disabled SDK does not capture any new traces, nor does it use up system resources.

  • type: boolean
  • Can be set by using an environment variable 'POSTMAN_SDK_ENABLE' , which will over-ride any other config

• debug: Enable/Disable debug logs.

  • type: boolean

• truncateData: Truncate the request and response body so that no PII data is sent to Postman. This is enabled by default. Disabling it sends actual request and response payloads.

  • type: boolean

  • default: true

  • Example:

    Sample payload or non-truncated payload:

    {
        "first_name": "John",
        "age": 30
    }
    

    Truncated payload:

    {
        "first_name": {
            "type": "String"
        },
        "age": {
            "type": "Number"
        }
    }
    

• redactSensitiveData: Redact sensitive data such as api_keys and auth tokens, before they leave the sdk. When this is enabled, below redaction rules are applied by default (they are not case-sensitive):

    {
        "pmPostmanAPIKey": "PMAK-[a-f0-9]{24}-[a-f0-9]{34}",
        "pmPostmanAccessKey": "PMAT-[0-9a-z]{26}",
        "pmBasicAuth": "Basic [a-zA-Z0-9]{3,1000}(?![a-z0-9+({})!@#$%^&|*])[=]{0,2}",
        "pmBearerToken": "Bearer [a-z0-9A-Z\-\._~\+\/]{15,1000}"
    }
  

  • type: Object {enable: true/false, rules: {ruleName: '<regexPattern>'}}

  Example

  initialize(
    collectionId: '<postmanCollectionId>'
    apiKey: '<apiKey>',
    redactSensitiveData: {
      enable: true, // default
      rules: {
        apiToken: 'PMAK-[a-f0-9]' // Sample rule, you can add your own regex
      }
    }
  )
  

• ignoreIncomingRequests: Return true/false to ignore incoming request from Live Collection

  • type: Function(request: http.IncomingMessage) : boolean
  • For propertires available on request see: https://nodejs.org/docs/latest-v14.x/api/http.html#http_class_http_incomingmessage

  Example

  initialize({
    ...otherParams,
    ignoreIncomingRequests: (request) => {
      return request.url.includes('knockknock');
    }
  });
  

• ignoreOutgoingingRequests: Return true/false to ignore outgoing request from Live Collection

  • type: Function(request: requestOptions) : boolean
  • For propertires available on request see: https://nodejs.org/api/http.html#httprequesturl-options-callback

  Example

  initialize({
    ...otherParams,
    ignoreOutgoingRequests: (request) => {
      return request.headers['User-Agent'].includes('ignoreme');
    }
  });
  

• samplingRatio - The ratio in which the traces generated should be sampled.

  • type: number
  • default: 1
  • For Example: 0.1 sampling ratio means 10% of the traces sampled.

• transformations - transformations to be applied on the request/response before sending to Postman. The transformations are applied in the order they are specified.

  • type: Array of type Transformation
  • Supported transformation:
    • DROP - drops the specified header/queryParam from the request/response
    • REDACT - redacts the specified header/queryParam from the request/response

  Example

  const {
    initialize,
    TransformationAction,
    TransformationSource
  } = require('@postman/postman-sdk');
  
  initialize({
    collectionId: <collection_id>,
    apiKey: '<postman_api_key>',
    transformations: [
      {
        name: ['x-aws-region', 'x-route-key'],
        source: TransformationSource.HEADERS,
        action: TransformationAction.DROP
      },
      {
        name: ['x-secret-key', 'x-aws-key'],
        source: TransformationSource.QUERY_PARAMS,
        action: TransformationAction.REDACT
      }
    ]
  });