Finding your way on the API Manager roads

A question that quickly arises when configuring IAM (aka Kong Gateway) is how many routes should be created to reach all the business objects in an IRIS API.

A common mistake is to create one route per business object, unnecessarily multiplying the number of routes.

Let's take the example of the Supply Chain Orchestrator Data Model API:

/api/SC/scmodel/v1/objects
/api/SC/scmodel/v1/objects/BOM
/api/SC/scmodel/v1/objects/Carrier
/api/SC/scmodel/v1/objects/Customer
/api/SC/scmodel/v1/objects/DemandPlan
/api/SC/scmodel/v1/objects/InventoryThreshold
/api/SC/scmodel/v1/objects/Issue
/api/SC/scmodel/v1/objects/LeadtimeVariant
/api/SC/scmodel/v1/objects/Location
/api/SC/scmodel/v1/objects/MfgOrder
/api/SC/scmodel/v1/objects/Milestone
/api/SC/scmodel/v1/objects/Product
/api/SC/scmodel/v1/objects/ProductInventory
/api/SC/scmodel/v1/objects/ProductSupplier
/api/SC/scmodel/v1/objects/ProductionCapacity
/api/SC/scmodel/v1/objects/PurchaseOrder
/api/SC/scmodel/v1/objects/PurchaseOrderLine
/api/SC/scmodel/v1/objects/RouteLeg
/api/SC/scmodel/v1/objects/SCException
/api/SC/scmodel/v1/objects/SLA
/api/SC/scmodel/v1/objects/SalesOrder
/api/SC/scmodel/v1/objects/SalesOrderLine
/api/SC/scmodel/v1/objects/SalesShipment
/api/SC/scmodel/v1/objects/SalesShipmentLine
/api/SC/scmodel/v1/objects/ServiceSLA
/api/SC/scmodel/v1/objects/ShipmentMilestone
/api/SC/scmodel/v1/objects/ShipmentStop
/api/SC/scmodel/v1/objects/ShipmentTracking
/api/SC/scmodel/v1/objects/ShippingCost
/api/SC/scmodel/v1/objects/Supplier
/api/SC/scmodel/v1/objects/SupplyPlan
/api/SC/scmodel/v1/objects/SupplyShipment
/api/SC/scmodel/v1/objects/SupplyShipmentLine
/api/SC/scmodel/v1/objects/TrackingService

Creating a route in API Manager for each business object would be tedious and strongly discouraged, and would not protect you from changes during a version upgrade.

Example of a clean cut (recommended)

Kong doesn't natively understand /objects/{type}.

👉 It needs to be translated using a regex :

{type} = [^/]+

We start by creating a service scmodel in Kong 

### Create a new service in Kong for the SC Model application
curl -i -X POST \
--url http://localhost:8001/services/ \
--data 'name=scmodel' \
--data 'url=http://192.168.65.1:52880'

Then we add the route to retrieve the list of all objects with $ for the exact routes:

### Create a route for the SC Model service Objects
curl -i -X POST \
--url http://localhost:8001/services/scmodel/routes \
--data 'name=scmodel-objects' \
--data 'paths=~/api/SC/scmodel/v1/objects$' \
--data 'strip_path=false'

Then we create a generic route for all object type using [^/]+$ as the regex :

### Create a route for the SC Model for all object types
curl -i -X POST \
  http://localhost:8001/services/scmodel/routes \
  --data name=scmodel-object-type \
  --data 'paths[]=~/api/SC/scmodel/v1/objects/[^/]+$' \
  --data strip_path=false

If you want to monitor or manage one type of object in particular with different plugins or different auth, rate-limits, etc., you have to create a specific route for it, using regex_priority:

If multiple regex routes match, Kong chooses the highest regex_priority, otherwise… the internal (non-deterministic) order.

Example below for Customer and Product objects :

### Create a route for the SC Model service Customer
curl -i -X POST \
  http://localhost:8001/services/scmodel/routes \
  --data name=scmodel-object-customer \
  --data 'paths[]=~/api/SC/scmodel/v1/objects/Customer$' \
  --data 'regex_priority=10' \
  --data strip_path=false

### Create a route for the SC Model service Product
curl -i -X POST \
  http://localhost:8001/services/scmodel/routes \
  --data name=scmodel-object-product \
  --data 'paths[]=~/api/SC/scmodel/v1/objects/Product$' \
  --data 'regex_priority=10' \
  --data strip_path=false

You can also create a limited list of objects types by using regex (A,B,C).
Example below for all sales routes :

### Create a route for the SC Model Sales routes
curl -i -X POST \
  http://localhost:8001/services/scmodel/routes \
  --data name=scmodel-object-sales \
  --data 'paths[]=~/api/SC/scmodel/v1/objects/(SalesOrder|SalesOrderLine|SalesShipment|SalesShipmentLine)$' \
  --data 'regex_priority=10' \
  --data strip_path=false

You can then find the route configuration in the API Manager portal :

To test it, just make some calls to different routes :

### Get Object BOM
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/BOM'

### Get Object Carrier
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/Carrier'

### Get Object Customer
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/Customer'

### Get Object DemandPlan
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/DemandPlan'

### Get Object InventoryThreshold
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/InventoryThreshold'

### Get Object Issue
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/Issue'

### Get Object Product
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/Product'

### Get Object SalesOrder
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/SalesOrder'

### Get Object SalesOrderLine
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/SalesOrderLine'

### Get Object SalesShipment
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/SalesShipment'

### Get Object SalesShipmentLine
curl --user _SYSTEM:SYS 'http://localhost:8000/api/SC/scmodel/v1/objects/SalesShipmentLine'

This allows you to manipulate your Customer business object with a finer level of detail than other objects types:

Analytics for all sales objects :

Analytics of the other object types :