From Postman or OpenAPI to an SAP CPI HTTP Receiver

Most REST APIs you connect from SAP CPI arrive with an OpenAPI or Swagger file, a Postman collection, or both. Everything the HTTP receiver adapter needs is in them: the server, the path, the parameters, the headers and the shape of the body. The work is moving each piece to the right field without dropping a character.

This article maps an OpenAPI operation and a Postman request onto the HTTP receiver, step by step, and lists the details that most often break the first call.

What the HTTP receiver needs

• Address: the full URL of the operation. It can contain Simple expressions, such as ${property.orderId} for a path parameter.
• Query: the query string without the ?, for example notify=true.
• Method: GET, POST, PUT, PATCH or DELETE.
• Authentication: none, Basic, Client Certificate, OAuth2 Client Credentials and others, using credentials stored in the tenant, never typed into the channel.
• Request Headers: the names of the message headers that are sent to the API, separated by |.
• The body: whatever the message body is when it reaches the adapter, usually built in a Content Modifier or a mapping.

Reading an OpenAPI or Swagger operation

Take this OpenAPI 3 operation, which creates a shipment for an order:

openapi: 3.0.3
servers:
  - url: https://api.example.com/v1
paths:
  /orders/{orderId}/shipments:
    post:
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string } }
        - { name: notify, in: query, schema: { type: boolean } }
        - { name: X-Request-Id, in: header, schema: { type: string } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                carrier: { type: string }
                trackingNumber: { type: string }

1. Address: join the server URL and the path. In Swagger 2.0 the server is split into schemes, host and basePath.
2. Path parameters such as {orderId}: replace each with an expression, for example ${property.orderId}.
3. Query parameters (in: query): move them to the Query field.
4. Header parameters (in: header): set them as message headers in a Content Modifier and list their names in Request Headers.
5. Request body: build the JSON in a Content Modifier, following the schema under requestBody.
6. Security schemes: create the matching credential in the tenant and select it under Authentication.

The result: a Content Modifier and the channel

For this operation, the Content Modifier before the adapter and the HTTP receiver channel look like this:

Content Modifier
  Header   Content-Type   application/json
  Header   X-Request-Id   ${property.requestId}
  Body     {
             "carrier": "${property.carrier}",
             "trackingNumber": "${property.trackingNumber}"
           }

HTTP receiver
  Address           https://api.example.com/v1/orders/${property.orderId}/shipments
  Query             notify=true
  Method            POST
  Request Headers   Content-Type|X-Request-Id

The Content Modifier sets the Content-Type header to application/json, the X-Request-Id header and the JSON body, with the values taken from exchange properties set earlier in the flow. Request Headers lists exactly the two headers the API should receive, so every other header stays in the tenant.

From a Postman request

A Postman request carries the same information in different places:

• The URL often starts with a Postman variable such as {{baseUrl}}. In SAP CPI the same {{…}} syntax means an externalized parameter, set when you deploy: a natural home for the base URL, which changes between test and production.
• Path variables (:orderId) and query parameters map to the Address and Query fields as above.
• The Headers tab becomes Content Modifier headers plus their names in Request Headers.
• A raw JSON body becomes the Content Modifier body, with each test value replaced by an expression.
• The Authorization tab tells you which authentication to configure. Do not copy a token from Postman into the iFlow; store credentials in the tenant.

Details that break the first call

• Request Headers set to * sends every message header to the API, including internal ones. List only the headers the API expects.
• A missing or wrong Content-Type header: many APIs reject a JSON body without application/json.
• Values in the URL must be URL-safe: an ID containing spaces or slashes needs encoding before it goes into the address.
• Error responses: with Throw Exception on Failure switched off, the flow continues and ${header.CamelHttpResponseCode} holds the status code, so a Router can handle errors.
• Field names in the JSON body are case-sensitive for most APIs; copy them from the schema, not from memory.

Calling an OData service instead? See the OData receiver article. For the expressions used in the address and body, see Camel Simple expressions in SAP CPI.

How Kitegra helps

The Kitegra browser extension takes the API specification for you. Give it an OpenAPI or Swagger file, in JSON or YAML, or a Postman collection, and in the SAP Integration Suite designer it suggests the URLs, paths, query parameters, request headers and example JSON bodies from that specification.

The specification stays in your browser: Kitegra never stores API specs. It never saves, deploys or edits an iFlow's content, and your tenant changes only when you click one of four named actions, which can be switched off.

To call your own iFlow's HTTPS endpoint the same way, see testing an HTTPS iFlow with a service key.

Without an account it works on 5 iFlows per module. The Free plan covers 50, Starter 100 and Pro 300. On the team plans every member gets Pro, with 300 iFlows per module on Startup Team and no limit on Growth Team and Scale Team. While Kitegra launches, every tool is open to everyone signed in, on the Free plan too. Compare the plans.

Try it in your next iFlow

Read what Kitegra does in the SAP Integration Suite designer, or see it next to its modules.

Frequently asked questions