Allowable Values In Service Configuration

[dkelosky]

Looking here: https://docs.zowe.org/stable/extend/extend-apiml/onboard-plain-java-enabler.html#configuring-your-service

Is there a way to present for all fields that are accepted in a service configuration:

• if a field is optional or required
• if it has a default value and what it is
• what is best practice

Fir the first, some fields have (Optional) near them - are the rest required? If they have acceptable defaults, are they still required to go into a yml file?

Are homePageRelativeUrl, healthCheckRelativeUrl, and statusPageRelativeUrl all required?

Is it typically necessary that gateway and service URL mappings need to be listed? e.g.:

routes:
    - gatewayUrl: api/v1
      serviceUrl: /sampleservice/api/v1

fyi @ChrisBoehmCA

[balhar-jakub]

We will update the documentation to clarify these topics. Thanks for the feedback.

To answer your questions:

• If you are using the enabler directly, the enabler doesn't provide defaults for these values. As such if the value isn't provided, it will be missing which may impact the behavior of the API Gateway and/or API Catalog. So I would say they are required if you want to have full functionality of the API ML, but omitting some of them isn't going to break the whole behavior.
• As for homePageRelativeUrl, healthCheckRelativeUrl, and statusPageRelativeUrl - the homePageRelativeUrl could be empty and it's ok. For the remaining two we expect the values.
• gatewayURL and serviceURL is required as it explains the mapping between external URL that the user uses to access the Gateway and internal one that Gateway uses to actually access the service.

If this answers the questions I will remove the question label and keep it as the enhancement to the documentation that we also should do.

[balhar-jakub]

@ChrisBoehmCA Did the answer help?

[ChrisBoehmCA]

Yes thanks for the explanation and for looking into updating the documentation. I think when you explore updating the documentation it would be useful to explain what features will not be available if any of these values are omitted. For instance for the three URLs mentioned in your second bullet point, explaining the meaning and specification of those endpoints would be helpful. I'm a little confused by apiInfo.version as well. On the page the examples of 1.0.0 and v1 are both given for this field. Should the apiInfo.version match the API spec exactly (v1)? Or is it intended to be a version internal to the service that can then be mapped to the API spec like the 1.0.0 example which would map to /api/v1?

[balhar-jakub]

@ChrisBoehmCA Thanks for the feedback, I will definitely make sure to include these topics. To answer your question around versioning.

What are the requirements around the version?

1. In the URL the version needs to start with the v. Apart from that as long as it is a valid URL it could contain Semantic versioning as well as just a major version. So v1 as well as v1.0.0 is valid and should work. The guidance is to use just the major version here as long as you follow the semantic versions and minor and patch versions don't introduce breaking changes.
2. In the apiInfo.version again it is Ok to specify just the major version or the whole semantic version, but without the starting v. The guidance is to use the semantic version here as this information is visible in the API Catalog and can help the user understand what exact version of the API is available.

So to answer the apiInfo.version is expected to be a more detailed version such as a specific version of the API or product while the /api/v1 is expected to be a relatively stable URL where only Major version introduces breaking changes and as such it's ok to keep only the major version in the URL.

[ChrisBoehmCA]

Thanks. I think that information should be included in the documentation.

[anton-brezina]

@dkelosky and @ChrisBoehmCA we believe that this is addressed by the new onboarding wizard. Are you ok to close this issue? Thanks.

[dkelosky]

I think the wizard is helpful and a great step. I also think though that the doc could describe required / optional / default parameters and perhaps examples values for troubleshooting, debugging, and covering cases where customization is needed even after using the wizard.

[CarsonCook]

We could provide a JSON schema for this, improving the experience when creating this file, and then generate documentation on docs-site from the schema.