serviceId problems when onboarding static API
@balhar-jakub is already working on this.
Since Oct 22, 2025.
- Dominant language
- Java
- Stars
- 92
- Forks
- 81
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 46
Description
Describe the bug
When onboarding a static API, I've run into issues with the serviceId and the swagger docs.
According to the following documentation:
https://docs.zowe.org/stable/extend/extend-apiml/onboard-plain-java-enabler
"The serviceId uniquely identifies one or more instance of a microservice in the API ML and is used as part of the service URL path in the API ML Gateway address space."
In my case, suppose the base URL for my service is:
https://:/myapi/
I should be able to specify a serviceId according to this these naming rules shown in the docs for serviceId (by the way, I think these should say "serviceId", not "service_d_Id"):
"The same servicedId should only be set for multiple API service instances for API scalability.
The servicedId value must only contain lowercase alphanumeric characters.
The servicedId cannot contain more than 40 characters."
So, I should be able to specify "acmemyapi" as the serviceId, as per this example:
services:
- serviceId: **acmemyapi**
title: My API Service
description: My API Service description
catalogUiTileId: acmemyapitile
instanceBaseUrls:
- https://<host>:<port>/myapi/
routes:
- gatewayUrl: /api/v1/
serviceRelativeUrl: /api/v1/
authentication:
scheme: zoweJwt
apiInfo:
- apiId: acme.myapi
version: 1.0
gatewayUrl: /api/v1/
swaggerUrl: https://<host>:<port>/myapi/api-docs/swagger.json
When I do, I can see my onboarded API in the catalog and I can view the swagger documentation for it but when I try to exercise APIs from the embedded swagger, I run into problems.
For example, instead of having the swagger call this:
https://:7554/acmemyapi/api/v1/stuff
It calls this:
https://:7554/myapi/api/v1/stuff
and fails with:
{
"messages": [
{
"messageType": "ERROR",
"messageNumber": "ZWEAO404E",
"messageContent": "The service can not find the requested resource.",
"messageKey": "org.zowe.apiml.common.notFound"
}
]
}
and I can see this occurs because "myapi" is not the serviceId.
I notice that outside of the swagger I can successfully call this: https://:7554/acmemyapi/api/v1/stuff so API ML seems to be using the supplied serviceId correctly, just not with swagger.
The only way I can work around this is by changing the serviceId to be "myapi" but I should be able to name it anything that conforms to the documented rules.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.