Common Patterns

This page describes conventions that apply across all API endpoints.

Request format

All requests that include a body must use JSON:

curl -X POST "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/apis" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-api", "displayName": "My API", "status": "ACTIVE", "tags": [] }'

Pagination

List endpoints return paginated results wrapped in a SimplePage envelope:

{
  "content": [ ... ],
  "size": 10,
  "number": 1,
  "totalPages": 5,
  "totalElements": 42,
  "last": false
}

Field	Type	Description
content	array	The items for the current page
size	integer	Number of items per page
number	integer	Current page number (1-based)
totalPages	integer	Total number of pages
totalElements	integer	Total number of items across all pages
last	boolean	true if this is the last page

Query parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
size	integer	10	Number of items per page
sort	string	varies	Sorting criteria: property,(asc|desc). Supports multiple sort criteria.

Example: Get the second page of 20 APIs, sorted by name:

curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/apis?page=2&size=20&sort=name,asc" \
  -H "Authorization: Bearer <your-token>"

Iterating through all pages

To retrieve all items, loop until last is true:

PAGE=1
while true; do
  RESPONSE=$(curl -s -X GET \
    "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/apis?page=$PAGE&size=100" \
    -H "Authorization: Bearer <your-token>")

  echo "$RESPONSE" | jq '.content[]'

  IS_LAST=$(echo "$RESPONSE" | jq '.last')
  if [ "$IS_LAST" = "true" ]; then break; fi

  PAGE=$((PAGE + 1))
done

Error responses

Errors return a standard JSON structure:

{
  "timestamp": "2026-02-23T10:30:00.000+00:00",
  "status": 404,
  "error": "Not Found",
  "message": "API with id a1b2c3d4 not found",
  "path": "/apis/a1b2c3d4"
}

Field	Type	Description
timestamp	string	When the error occurred
status	integer	HTTP status code
error	string	HTTP status text
message	string	Human-readable error description
path	string	Request path that caused the error

Common HTTP status codes

Status	Meaning
200	Success
201	Created (for POST requests)
204	No Content (for DELETE requests)
400	Bad Request — invalid input
401	Unauthorized — missing or invalid token
403	Forbidden — insufficient permissions
404	Not Found — resource does not exist
409	Conflict — duplicate resource
500	Internal Server Error

Filtering

Most list endpoints support filtering via query parameters. Common filter parameters include:

Parameter	Description	Example
text	Free-text search across name and description	?text=petstore
name	Filter by exact name	?name=my-api
status	Filter by status	?status=ACTIVE
tags	Filter by tags	?tags=production&tags=v2
owner	Filter by owner (UUID)	?owner=a1b2c3d4-...
platformType	Filter by gateway platform	?platformType=BOOMI

Resource identifiers

Resources are identified by UUIDs:

a1b2c3d4-e5f6-7890-abcd-ef1234567890

These are used in path parameters (e.g., /apis/{id}) and in request/response bodies when referencing related resources.

Image upload and download

Several resources (APIs, API Products, Users, Developer Portals) support image management:

Operation	Method	Path
Upload image	PUT	/{resource}/{id}/image
Download image	GET	/{resource}/{id}/image
Delete image	DELETE	/{resource}/{id}/image

Image upload uses multipart/form-data:

curl -X PUT "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/apis/<api-id>/image" \
  -H "Authorization: Bearer <your-token>" \
  -F "file=@logo.png"

Asynchronous operations

Some operations (like deployments) run asynchronously. These return a job ID that you can poll:

# Start a deployment (returns job info)
curl -X PUT "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/environments/<env-id>/apis/<api-id>" \
  -H "Authorization: Bearer <your-token>"

# Check running jobs
curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/runningJobs" \
  -H "Authorization: Bearer <your-token>"

Job history is available at:

curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/jobs?page=1&size=10" \
  -H "Authorization: Bearer <your-token>"