From 37b6ac9b22eb3225826088a7ff1c645e05d4632a Mon Sep 17 00:00:00 2001 From: Pablo Carle Date: Wed, 16 Oct 2024 08:46:47 +0200 Subject: [PATCH 1/2] use API Catalog with Graphql (#3953) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Pablo Hernán Carle Co-authored-by: Pablo Hernán Carle --- docs/user-guide/api-mediation/use-graphql-api.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/api-mediation/use-graphql-api.md b/docs/user-guide/api-mediation/use-graphql-api.md index f0c7f9d429..3ed3b5fa21 100644 --- a/docs/user-guide/api-mediation/use-graphql-api.md +++ b/docs/user-guide/api-mediation/use-graphql-api.md @@ -1,15 +1,18 @@ # Using GraphQL APIs -GraphQL is a query language for APIs that provides descriptions of the data in your APIs, and allows for specific queries to facilitate API development. Routing for such APIs is possible within the Zowe ecosystem, however at the present time, Zowe itself does not provide any GraphQL APIs. +GraphQL is a query language for APIs that provides descriptions of the data in your APIs, and allows for specific queries to facilitate API development. Routing for such APIs is possible within the Zowe ecosystem, however at the present time, Zowe itself does not provide any GraphQL APIs. For more information about configuring routing to API ML, see the following articles: + * [Implementing routing to the Gateway](../../extend/extend-apiml/implementing-routing-to-the-api-gateway) * [Routing Requests to REST API](./routing-requests-to-rest-apis) :::tip + * For information about how to use GraphQL, see [GraphQL Best Practices](https://graphql.org/learn/best-practices/) in the GraphQL product documentation. * For information about how to use HTTP to deliver the GraphQL interface, see [Serving over HTTP](https://graphql.org/learn/serving-over-http/) in the GraphQL product documentation. + ::: ## Difference between GraphQL APIs and traditional REST APIs @@ -67,10 +70,9 @@ GraphQL supports subscriptions, which allow clients to subscribe to real-time up - **Strongly Typed** GraphQL APIs are strongly typed so that every operation is checked and validated against the schema, leading to more reliable and predictable APIs. -## Limitations for the API Mediation Layer +## Displaying GraphQL in API Catalog -The documentation for the GraphQL is not provided via the standard OpenAPI protocol, but rather, for the most part are living as a sandbox environment within the GraphQL applications. +Since Zowe v3, it is possible to configure the service to display an interactive documentation UI inside the API Catalog services' detail page. -:::tip -The API Catalog currently does not support visualization of GraphQL APIs. As such, we recommend that extenders provide a link to the GraphQL endpoint via the Open API for the API Catalog. -::: \ No newline at end of file +This capability is enabled in the API Catalog by default. +It requires the service to onboard to the Discovery Service with `apiml.apiInfo.api-.graphqlUrl` set to the endpoint where the service exposes the GraphQL API. From c97c67f5cf1e42fc393e9e9dfd42e8f9c7d79d27 Mon Sep 17 00:00:00 2001 From: zowe-robot <42546701+zowe-robot@users.noreply.github.com> Date: Wed, 16 Oct 2024 04:44:51 -0400 Subject: [PATCH 2/2] Update error codes (#3954) Signed-off-by: Zowe Robot Co-authored-by: Zowe Robot --- docs/troubleshoot/troubleshoot-apiml-error-codes.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/troubleshoot/troubleshoot-apiml-error-codes.md b/docs/troubleshoot/troubleshoot-apiml-error-codes.md index 691e07de7f..f93c212b4c 100644 --- a/docs/troubleshoot/troubleshoot-apiml-error-codes.md +++ b/docs/troubleshoot/troubleshoot-apiml-error-codes.md @@ -1,7 +1,7 @@ # Error Message Codes -The following error message codes may appear on logs or API responses. Use the following message code references and the corresponding reasons and actions to help troubleshoot issues. +The following error message codes may appear on logs or API responses. Use the following message code references and the corresponding reasons and actions to help troubleshoot issues. ## API mediation utility messages @@ -1129,7 +1129,7 @@ The following error message codes may appear on logs or API responses. Use the f Review the mentioned static API definition file for errors. Refer to the specific log message to determine the exact cause of the problem: - + - ServiceId is not defined in the file '%s'. The instance will not be created. Make sure to specify the ServiceId. - The `instanceBaseUrls` parameter of %s is not defined. The instance will not be created. Make sure to specify the `InstanceBaseUrl` property. - The API Catalog UI tile ID %s is invalid. The service %s will not have an API Catalog UI tile. Specify the correct catalog title ID. @@ -1488,7 +1488,7 @@ The following error message codes may appear on logs or API responses. Use the f - The URI is not valid. Ensure the service is providing a valid URL. - Not able to select a route for the URL of the specific service. The original URL is used. If necessary, check the routing metadata of the service. - The path of the service URL is not valid. Ensure the service is providing the correct path. - + ### ZWEAC706E @@ -1528,7 +1528,7 @@ The following error message codes may appear on logs or API responses. Use the f - The URI is not valid. Ensure the service is providing a valid URL. - Not able to select a route for the URL of the specific service. The original URL is used. If necessary, check the routing metadata of the service. - The path of the service URL is not valid. Ensure the service is providing the correct path. - + ### ZWEAC709E