Sample Script to convert PostMan Collection OpenAPI 3.x into compatible IBM APIC Import

collection2apic.sh

#!/bin/sh
# Quick Migration Script to convert a PostMan Collection OpenAPI 3.x into a compatible IBM APIC Import
# Author:  Sanjay Joshi (joshisa(AT)us.ibm.com)
# Version: 0.5
# Orig Date: Dec. 11, 2024
# Latest Edit Date: Jan 8, 2025
# EXAMPLE
#   COLLECTIONID: 18514645-20754862-8c19-45c8-9844-dda0967e4deb
#   POSTMAN COLLECTION WEB URL: https://www.postman.com/metaverse9000/book-store/collection/9urcs5u/collection-simple-book-api?ctx=info

COLLECTIONID=$1  #"POSTMAN-COLLECTION-ID-OF-INTEREST" as an argument
APIKEY="FILL-ME-IN-WITH-YOUR-POSTMAN-APIKEY"

clear 

if [ "$APIKEY" == "FILL-ME-IN-WITH-YOUR-POSTMAN-APIKEY" ]; then
  # Alert user that they have not entered their POSTMAN APIKEY
  echo "!!! Please update the script with your POSTMAN APIKEY value before running"
  exit 1
fi

if [ $# -eq 0 ]; then
    echo "!!! Please provide a Postman CollectionID as an argument for this script to fetch"
    exit 1
fi

# This POSTMAN API Call will generate an OpenAPI 3.x Document for a provided CollectionID
echo "Fetching OpenAPI 3.x document for Post Collection $COLLECTIONID"
curl --location --request GET 'https://api.getpostman.com/collections/'"$COLLECTIONID"'/transformations' --header 'Content-Type: application/json' --header 'x-api-key: '"$APIKEY"'' | jq -r '.output' > postman-openapi-$COLLECTIONID.json

sleep 2

# Patching in Stub Security Scheme Definition as a best practice
echo "Generating 'apic-friendly-secure.json' JSON document with Stub Security Scheme Definition for best practice validation ..."
cat postman-openapi-$COLLECTIONID.json | jq -r '. += {"components":{"securitySchemes":{"SecSchemeStub":{"type":"apiKey","x-key-type":"client_id","name":"X-IBM-Client-Id","in":"header"}}},"security":[{"SecSchemeStub":[]}]}' > apic-friendly-secure.json

sleep 2

# Beginning Outer Loop to iterate through all enumerated server URL values with Counter set to zero
echo "Reading Server URL field ..."
URL=$(cat apic-friendly-secure.json | jq '.servers[].url')
echo "Discovered Server URL field $URL ..."

sleep 2

# Updating target-url property to include request.path and populating target-url property value with Server text string
echo "Populating target-url property and updating invoke definition ..."
cat apic-friendly-secure.json| jq -r --argjson URL "$URL" '. += {"x-ibm-configuration":{"assembly":{"execute":[{"invoke":{"version":"2.0.0","title":"invoke","target-url":"$(target-url)$(request.path)",}}]},"properties":{"target-url":{"value":'"$URL"',"description":"The URL of the target service","encoded":false}}}}' > apic-friendly-secure-import.json

sleep 2

# initialize tmp file for in-place file overwrite
echo "Replacing Server URL entry with forward slash to ensure proper url construction"
tmp=$(mktemp)
# Safe to clear out server url values and replace with a forward slash to maintain proper url construction
jq -r '.servers |= [{"url":"/"}]' apic-friendly-secure-import.json > "$tmp" && mv "$tmp" apic-friendly-secure-import.json

sleep 2

# Output APIC Friendly Import OpenSpec 3.x Document to screen
echo ""
echo "Generated Files:"
echo " postman-openspec-$COLLECTIONID.json ('Postman Openspec 3.x Document from collection with ID $COLLECTIONID')"
echo " apic-friendly-secure.json ('Postman Openspec Document with Stub Security Scheme Definition')"
echo " apic-friendly-secure-import.json ('Patched Openspec Document with Stub Security, populated target-url and updated invoke definition. This should be used for IBM APIC Import')"
echo ""
echo ""
cat apic-friendly-secure-import.json
echo ""
echo "DONE!"

Example of the enrichment to the JSON happening in Line 35

Example of the enrichment to the JSON happening in Line 35 Plus Line 48.

This content is appended as extra elements at the end of the JSON OpenAPI 3.x doc.