api-layer
api-layer copied to clipboard
zowe
Enable API ML to validate conformance of APIs
Build functionality into the API ML, allowing it to validate conformance or otherwise of APIs to give developers advance notice and adjust before applying for Conformance.
There are many ways to achieve this, but the idea is to provide visibility to the developer on Conformance. For example, APIs could be shown as non-conformant in the API Catalog.
APIs shouldn't be rejected based on non-conformance. However, this could be configurable. The default should be to allow even non-conformant APIs.
Work
The first step is to understand the conformance criteria provided by the API ML here: https://ibm.box.com/s/rdb7zfkcxzzbiro4idat9o7xd0qig3mt
The next step is to prepare REST API, which will accept serviceId. The REST API will be part of the Gateway Service and will be publicly available. Upon call, it will do the validation and then return either 200, meaning that it is a valid request, or 400 with the explanation of what is wrong. At this stage, it will always return 200.
Test the serviceId, mainly whether it's up to 64 characters and only formed from valid characters.
The next step is to validate that the service is onboarded to the API ML. Meaning at the very least that the service is visible within the Discovery Service. As a part of this, the service supporting the endpoint needs to download the metadata provided by the service.
For the next step, the validation service needs to load the Swagger documentation from provided URL and verify that it's either valid Swagger, OpenAPI 2, or OpenAPI 3.
For the next step, we take URLs from the provided Swagger document. The service will validate that calling these APIs through the Gateway is possible. This verifies that the API is valid. On top of that, it must verify that the path either is unversioned or is versioned properly.
The next step is to verify the Single Sign-On participation. This means that the token created by the API ML will be enough to authenticate against the authenticated REST endpoints when calling via Gateway.
Context
The Zowe project has a program for conformance. The program overall lives here: https://www.openmainframeproject.org/all-projects/zowe/conformance. In our case, we care about the conformance program for the API Mediation Layer. The conformance program is aimed at the developers and companies who create services that benefit from the functionality brought by the API Mediation Layer. One of their benefits is that they can use the Conformance badge in their PR, and they are also visible on the landscape on the Open Mainframe Project page.
To ensure that conformance means something, each squad provided the criteria. These criteria apply to the services in our case (API ML). These services need to be onboarded to the API Mediation Layer and follow a few other characteristics.
The specific characteristics are described in this document: https://ibm.box.com/s/rdb7zfkcxzzbiro4idat9o7xd0qig3mt
Ideally, at the end of the project, we will be able to take a service and claim whether the service is conformant. Right now, it's self-evaluation, so the company that asks for the conformance claims that they verified that they are conformant, and we just believe them.
The first step is to understand the conformance criteria provided by the API ML here: https://ibm.box.com/s/rdb7zfkcxzzbiro4idat9o7xd0qig3mt
The next step is to prepare REST API, which will accept serviceId. The REST API will be part of the Gateway Service and will be publicly available. Upon call, it will do the validation and then return either 200, meaning that it is a valid request, or 400 with the explanation of what is wrong. At this stage, it will always return 200.
Test the serviceId, mainly whether it's up to 64 characters and only formed from valid characters.
The next step is to validate that the service is onboarded to the API ML. Meaning at the very least that the service is visible within the Discovery Service. As a part of this, the service supporting the endpoint needs to download the metadata provided by the service.
For the next step, the validation service needs to load the Swagger documentation from provided URL and verify that it's either valid Swagger, OpenAPI 2, or OpenAPI 3.
For the next step, we take URLs from the provided Swagger document. The service will validate that calling these APIs through the Gateway is possible. This verifies that the API is valid. On top of that, it must verify that the path either is unversioned or is versioned properly.
The next step is to verify the Single Sign-On participation. This means that the token created by the API ML will be enough to authenticate against the authenticated REST endpoints when calling via Gateway.
Context
The Zowe project has a program for conformance. The program overall lives here: https://www.openmainframeproject.org/all-projects/zowe/conformance. In our case, we care about the conformance program for the API Mediation Layer. The conformance program is aimed at the developers and companies who create services that benefit from the functionality brought by the API Mediation Layer. One of their benefits is that they can use the Conformance badge in their PR, and they are also visible on the landscape on the Open Mainframe Project page.
To ensure that conformance means something, each squad provided the criteria. These criteria apply to the services in our case (API ML). These services need to be onboarded to the API Mediation Layer and follow a few other characteristics.
The specific characteristics are described in this document: https://ibm.box.com/s/rdb7zfkcxzzbiro4idat9o7xd0qig3mt
Ideally, at the end of the project, we will be able to take a service and claim whether the service is conformant. Right now, it's self-evaluation, so the company that asks for the conformance claims that they verified that they are conformant, and we just believe them.
