API metadata in API Gateway

API metadata is the central index that catalogs all suites, products, and operations available in API Gateway. It enables API discovery through the UI and provides a machine-readable catalog for other applications.

API metadata is the central index that catalogs all suites, products, and operations available in API Gateway. The API Gateway metadata indexing service scans the Swagger documentation attached to each endpoint and builds a searchable inventory of all API operations.

The metadata index serves two purposes. It supports browsing and searching APIs through Swagger UI. It also provides a machine-readable catalog that other applications, such as ION Workflow and APIFlow, use to discover available operations.

Who this affects

API Gateway administrators manage metadata indexing, trigger manual refreshes, and troubleshoot indexing issues. This role requires the ION API Administrator security role.

API developers ensure that endpoints include Swagger documentation so operations appear in the metadata index.

Integration developers use metadata to discover available suites, products, and operations when building integrations with ION Workflow, APIFlow, or other applications.

Business benefits

Centralized API discovery provides a single, searchable index of all API suites, products, and operations across the environment.

Automated catalog maintenance keeps the catalog current when API suites or endpoints are added, deleted, or updated.

Cross-application visibility enables other applications, such as ION Workflow and APIFlow, to query metadata and determine which operations are available.

How API metadata works

Automatic indexing

The API Gateway indexing service builds the metadata catalog by reading Swagger documentation from each registered endpoint.

Indexing is triggered automatically when an API suite is added, deleted, or updated.

Indexing is also triggered automatically when an API endpoint is added, deleted, or updated.

When triggered, the indexing service processes all registered endpoints and updates the catalog. A typical reindexing cycle takes between 15 minutes and 1 hour, depending on the number of endpoints.

Index freshness

Every tenant starts with preconfigured Infor suites, so the metadata index is not empty for new tenants.

API Gateway displays the last indexed time on the API Metadata page.

To keep the index current, trigger a metadata refresh after adding or updating endpoints. If a refresh is not triggered, the metadata can show stale data and recently added operations do not appear.

What gets indexed and limitations

Indexed data

The indexing service catalogs three levels of information from Swagger documentation.

Level Description
API suites Top-level collection of related APIs, such as Infor CRM or Infor M3.
Products Individual applications associated with the API suite. Products are identified by a logical ID prefix.
Operations Specific API operations, including HTTP method and path combinations, within an API endpoint.

Indexing limitations

WebSocket endpoints are not indexed because WebSocket does not support documentation.

GraphQL endpoints are not supported in API metadata.

Only Swagger documentation is parsed for metadata indexing. PDF and WSDL documents can be uploaded for endpoint reference purposes, but the indexing service does not use PDF or WSDL documents to populate the metadata catalog.

Default query behavior

SOAP operations are indexed by the metadata service, but SOAP operations are excluded from operation query results by default.

To include SOAP operations in query results, set the includeSoap parameter to true on operation endpoints, such as /operations or /apisuites/{suiteContext}/operations.

Metadata REST API

Overview

The Metadata API provides programmatic access to API suites, products, and operations in a tenant.

All endpoints use the GET method and are scoped to the authenticated tenant.

Base URL: /ionapi/metadata/v1/{tenant}

Authentication

All Metadata API endpoints require a valid OAuth 2.0 bearer token.

Requests without a valid token return a 401 Authorization Failed response.

The token must be scoped to the tenant specified in the base URL path.

For information about obtaining OAuth 2.0 credentials, see the Authorized Apps section of the ION API Administration Guide.

If you call the Metadata API from the Gateway UI, the Gateway UI generates the token.

API version

The API version is retrieved by calling GET /version.

The current version is 1.0.

The API is backward-compatible. Existing integrations continue to work across version updates without changes.

Suites, products, operations, and queries

The Metadata API exposes API suites, products, operations, search filters, and pagination controls.

API suite endpoints

Endpoint Description
GET /apisuites Returns all API suites for the current tenant. The endpoint supports fuzzy search by suite name, description, context, and product information.
GET /apisuites/{suiteContext} Returns detailed information for a specific API suite, including proxy paths.

API suite response properties

Property Type Description
suiteId string Unique identifier for the API suite.
proxyPaths array Proxy path entries associated with the suite. This property is returned by the single-suite endpoint only.
suiteContext string Unique context identifier used to reference the suite in API calls, such as INFORCRM or IDM.
type string Suite type classification, such as INFORPROVISIONED or NONINFOR.
description string Description of the API suite.
tenant string API Gateway tenant name.
name string API suite name.

API suite example

GET /ionapi/metadata/v1/tenant_ax1/apisuites?searchcriteria=CRM&pageSize=5
[
  {
    "suiteId": "tenantxprd_UUID1234",
    "proxyPaths": [
      "tenant_ax1/CRM/openweather/proxy"
    ],
    "suiteContext": "CRM",
    "type": "INFORPROVISIONED",
    "description": "CRM weather APIs",
    "tenant": "TENANT_AX1",
    "name": "CRM APIs"
  }
]

The example shows illustrative data. Actual suite names, contexts, and types vary by tenant configuration.

Product endpoints

Endpoint Description
GET /products Returns all products for the current tenant. The endpoint supports fuzzy search by name, description, or suite context.
GET /products/{logicalIdPrefix} Returns detailed information for a specific product, including associated API suites and proxy paths.
GET /apisuites/{suiteContext}/products Returns products within a specific API suite. The endpoint supports fuzzy search.
GET /apisuites/{suiteContext}/products/{logicalIdPrefix} Returns a specific product within a specific API suite.

Product response properties

Property Type Description
logicalIdPrefix string Logical identifier prefix of the product.
description string Description of the product.
name string Name of the product.

Product example

GET /ionapi/metadata/v1/{tenant}/apisuites/CRM/products
[
  {
    "name": "CRM Core",
    "description": "Core CRM services",
    "logicalIdPrefix": "lid://infor.crm"
  }
]

Operation endpoints

Endpoint Description
GET /operations Returns operations across all suites and products. The endpoint supports search and filtering.
GET /apisuites/{suiteContext}/operations Returns operations within a specific API suite.
GET /apisuites/{suiteContext}/products/{logicalIdPrefix}/operations Returns operations within a specific product of a specific suite.
GET /products/{logicalIdPrefix}/operations Returns operations for a specific product.
GET /scrollOperations Returns operations by using scroll-based pagination for large result sets.

Operation response properties

Property Type Description
swaggerOperationId string Operation ID as defined in the Swagger or OpenAPI document.
infoTitle string Title from the info section of the API specification.
logicalIdPrefix string Logical identifier prefix of the parent product.
method string HTTP method, such as GET, POST, PUT, or DELETE.
oauth2Scopes array of strings OAuth 2.0 scopes required to call the operation.
infoDescription string Description from the info section of the API specification.
suiteContext string Unique context identifier used to reference the suite in API calls, such as INFORCRM or IDM.
swaggerJsonFilePath string Path to the Swagger or OpenAPI JSON document for the operation.
operationSummary string Summary description of the operation.
proxyPath string Gateway proxy path for the operation.
productName string Name of the parent product.
uiFriendly string Indicates whether the operation is marked as UI-friendly by the x-ionapi-uifriendly extension.
restPath string REST path of the operation on the target service.
wsdlFilePath string Path to the WSDL document for SOAP operations.
wsdlOperationId string Operation ID as defined in the WSDL document for SOAP operations.

Operation example

GET /ionapi/metadata/v1/{tenant}/operations?searchcriteria=invoice&pageSize=3
[
  {
    "swaggerOperationId": "resource_datacompliance_invoice_POST",
    "infoTitle": "Data Compliance Rest API",
    "logicalIdPrefix": "infor.datacompliance",
    "method": "post",
    "oauth2Scopes": null,
    "infoDescription": "Post invoice audits.",
    "suiteContext": "DATACOMPLIANCE",
    "swaggerJsonFilePath": "https://mingle-ionapi.inforcloudsuite.com/TENANT_AX1/DATACOMPLIANCE/ionapi-doc",
    "operationSummary": "GdprAuditInvoice",
    "proxyPath": "TENANT_AX1/DATACOMPLIANCE/",
    "productName": "Data Compliance",
    "uiFriendly": null,
    "restPath": "/api/v1/mingle/gdpr/audit/invoice"
  },
  {
    "swaggerOperationId": "resource_M3Handler_retrieveAllInvoice_GET",
    "infoTitle": "M3 Financial API",
    "logicalIdPrefix": "infor.m3",
    "method": "get",
    "oauth2Scopes": null,
    "infoDescription": "Get M3 Invoices",
    "suiteContext": "M3",
    "swaggerJsonFilePath": "https://mingle-ionapi.inforcloudsuite.com/TENANT_AX1/M3/ionapi-doc",
    "operationSummary": "M3InvoiceHandler",
    "proxyPath": "TENANT_AX1/M3/",
    "productName": "Infor M3",
    "uiFriendly": null,
    "restPath": "/api/v1/m3/records/invoice"
  }
]

The example shows illustrative data. Actual operation details vary by tenant and suite configuration.

Search and filtering parameters

Parameter Applies to Description
searchcriteria Suites, products, operations Performs fuzzy search across names, descriptions, contexts, paths, and parameters.
suiteContext Operations Filters operations by a specific API suite context.
logicalIdPrefix Operations Filters operations by a specific product.
proxyPath Operations Performs a wildcard match on the gateway proxy path.
restPath Operations Performs a wildcard match on the REST path.
operationSummary Operations Matches words in the operation summary.
inputParameters Operations Matches words in the input parameters.
outputResponse Operations Matches words in the output response.
infoDescription Operations Matches words in the API info description.
includeSoap Operations Set to true to include SOAP operations with REST operations. By default, operation queries return REST operations only.
uiFriendly Operations Set to true to return only operations marked as x-ionapi-uifriendly in the API documentation.

Pagination parameters

Parameter Description
pageNo Specifies the page number. Page numbers are 1-based.
pageSize Specifies the number of results per page. The default is 10.
scroll Specifies how long the search context remains active for /scrollOperations.
scrollId Specifies the scroll identifier returned from the previous response. Use this value to retrieve the next batch of results.

Use page-based pagination for interactive browsing or when a specific page of results is required.

Use scroll-based pagination for bulk retrieval or export scenarios that iterate through the full result set. Use the /scrollOperations endpoint when the number of operations is too large to retrieve page by page.

Using and maintaining metadata

Getting started

You can access the metadata catalog in two ways: through the API Gateway administration console or by using the Metadata REST API.

A typical discovery workflow includes retrieving suites, retrieving products in a suite, retrieving operations, and retrieving the API specification.

  1. Call GET /apisuites to list API suites in the tenant.
  2. Call GET /apisuites/{suiteContext}/products to retrieve products in a suite.
  3. Call GET /apisuites/{suiteContext}/operations or GET /apisuites/{suiteContext}/products/{logicalIdPrefix}/operations to retrieve operations.
  4. Use the swaggerJsonFilePath value to access the API specification.

Ensuring APIs appear in metadata

Infor API suites are indexed automatically. Their Swagger documentation is included and requires no manual action.

Operations from Infor suites appear in the metadata catalog after the indexing service processes them.

For non-Infor API suites, perform these steps:

  1. Navigate to the API suite in the API Gateway administration console.
  2. Select the endpoint to document.
  3. Select Documentation, then select Add Documentation.
  4. Specify a name and URL, and select Swagger as the document type.
  5. Verify that the Swagger document is not larger than 4 MB.
  6. Select Save. The indexing service processes the documentation during the next indexing cycle.

For OpenAPI 3.x Swagger documents, ensure that the servers array contains an object with a url property. If the url property is missing, API Gateway cannot replace the URL with the correct Gateway-facing URL, and the Swagger try-it-out feature does not work.

Browsing the metadata catalog through the UI

  1. Open the API Gateway administration console.
  2. Navigate to the API Metadata page.
  3. Browse or search for suites, products, and operations.
  4. Select a suite to view its details.
  5. Review the Last Indexed timestamp displayed on the page to confirm that the catalog is current.

Querying the metadata catalog through the REST API

Use the Metadata REST API to discover APIs programmatically.

  1. Call GET /apisuites to list API suites in the tenant. Use the searchcriteria parameter to narrow results.
  2. Call GET /apisuites/{suiteContext}/products to retrieve products in a suite. Use the suiteContext value from the suite response.
  3. Call GET /apisuites/{suiteContext}/operations or GET /apisuites/{suiteContext}/products/{logicalIdPrefix}/operations to retrieve individual API operations.
  4. Use the swaggerJsonFilePath value from the operation response to access the full OpenAPI or Swagger document for the endpoint.

To search across all suites and products in one request, call GET /operations with the searchcriteria parameter.

Manual refresh

To update the index before the next automatic cycle, open the API Gateway administration console.

Navigate to the API Metadata page.

Select Refresh Metadata.

Wait for the refresh to complete. A typical refresh takes between 15 minutes and 1 hour, depending on the number of endpoints.

Limitations

For indexing limitations, see the Indexing limitations section.

For SOAP query behavior, see the Default query behavior section.

Troubleshooting

Operations not appearing in metadata:

Symptom: API operations are missing from the metadata index and may also be missing from ION Workflow, APIFlow, or other applications.

Resolution:

  1. Verify that the endpoint has valid Swagger documentation attached.
  2. Navigate to the API Metadata page and trigger a manual metadata refresh.
  3. Wait for the reindexing cycle to complete. This process typically takes 15 minutes to 1 hour.
  4. Confirm that the operations appear in the metadata catalog.

SOAP operations not appearing in query results:

Symptom: SOAP operations are indexed but do not appear when querying operation endpoints.

Resolution:

  1. Add includeSoap=true to the query parameters.

SOAP operations are excluded from query results by default.

Metadata indexing stuck in triggered status:

Symptom: After triggering a reindex, the status remains in a triggered state for an extended period.

Resolution:

  1. Create a temporary non-Infor API suite in API Gateway to restart the indexing service.
  2. Wait for the refresh cycle to complete.
  3. Verify that the indexing status has stabilized.
  4. Remove the temporary suite if it is no longer required.

401 Authorization Failed:

Symptom: Metadata API requests return a 401 Authorization Failed response.

Resolution:

  1. Verify that the OAuth 2.0 bearer token is valid and not expired.
  2. Confirm that the token is issued for the tenant that matches the {tenant} path segment in the base URL.
  3. Generate a new token if necessary and retry the request.

For information about creating and managing OAuth 2.0 credentials, see the Authorized Apps section of the ION API Administration Guide.

Additional API metadata information and troubleshooting

API Gateway metadata is an index of suites, products, and operations as defined in each endpoint’s Swagger documentation. The API Gateway indexing service runs when an API suite or endpoint is added, deleted, or updated.

You can search API Gateway metadata by using Swagger UI. Other applications also query metadata to determine available suites, products, and operations. To ensure that an API is included in metadata, add Swagger documentation to each endpoint as described in Adding API endpoint documentation.

Troubleshooting API metadata issues

Scenario 1: If operations do not appear in metadata, manually trigger metadata reindexing. This action also resolves missing operations in ION Workflow, APIFlow, and other applications.

Scenario 2: Metadata reindexing typically takes 15 minutes to 1 hour. If the indexing status remains in a triggered state for an extended time, create a temporary non-Infor suite to restart indexing. After the refresh completes, the status stabilizes.