Installing and Configuring GraphQL for the Akana API Platform

Provides information about Akana support of GraphQL, including general information about installing, configuring, and using GraphQL APIs.

For more information about how the API Admin and app developers work with GraphQL APIs in the developer portal, see GraphQL Support in the Developer Portal.

Valid in Version: 2022.1.0 and later

Table of Contents

Overview Information

Installing and Configuring Akana GraphQL Support

Reference Information

Overview Information

What is GraphQL?

GraphQL is a query language for APIs, that allows clients to be very specific about the information they are requesting. This facilitates streamlined processing. For example, two benefits:

  • The client can request information in a single GraphQL request that might previously have required multiple traditional REST API requests.
  • A traditional API response probably includes, as well as the information that the client needs, additional information that might not be useful. Using GraphQL, the client can request the specific fields/number of values needed, and the GraphQL endpoint returns only that information.

The Akana API Platform supports GraphQL from version 2022.1.0 onwards. The API must proxy an existing GraphQL service.

Additional resources for information about GraphQL:

Supported GraphQL version

The Akana API Platform supports the October 2021 Edition GraphQL specification, other than the exceptions noted in this documentation.

Akana API Platform support of GraphQL/Limitations

In 2022.1.0, for GraphQL, the following are supported:

  • For query and mutation operations:
    • Fields, Arguments, Operation Name, Variables, Mutations
  • For schemas and types
    • Type System, Type Language, Object Types and Fields, Arguments, Query and Mutation Types, List and Non-Null, Input Types

The following are not supported:

  • For query and mutation operations:
    • Aliases, Fragments, Directives, Inline Fragments
  • For schemas and types
    • Scalar Types, Enumeration Types, Interfaces, Union Types

Installing and Configuring Akana GraphQL Support

Installing GraphQL

If you want to support GraphQL APIs in your Akana API Platform, you'll need to install the following features:

  • In the container running the Policy Manager Management Console: GraphQL Management Support
  • In the container running the Network Director: GraphQL Runtime Support

For more information about product installation, refer to the installation doc: go to Installing the Akana API Platform.

Once you've completed your installation, you can create your first GraphQL API. However, you might want to modify the configuration settings. See Configuring GraphQL below.

Configuring GraphQL

The Akana Administration Console includes the following configuration settings for GraphQL, in the com.akana.graphql.binding configuration category:

graphql.in.binding.component.graphqlPayloadMaxSizeBytes
Sets a maximum message size, in bytes, for a GraphQL request, as a security precaution.
Default value: 524288 (512 KB)
graphql.in.binding.virtualhost.endpoint.selection.enabled
Enables/disables virtual host handling when selecting endpoints in GraphQL binding.
Default value: true

Using GraphQL APIs

To use a GraphQL API, first add the API in the Community Manager developer portal as usual.

Choose the I have an OAS3/Swagger/RAML/WSDL/WADL/GraphQL document option, and upload the GraphQL SDL (Schema Definition Language) file.

For details, see Adding an API in the developer portal help.

Notes:

  • Subscriptions are not supported in 2022.1.0. If the schema includes a subscription, the subscription is ignored.
  • You must provide the GraphQL API name, since name isn't included in the GraphQL SDL document.
  • You must provide the endpoint to proxy.

Security with GraphQL APIs

The Akana Platform allows you to configure access to operations using licensing or OAuth, for increased security.

In addition, you can disallow access to mutation operations. Access is controlled by licensing, or by OAuth scopes. Query/Mutation operations are restricted in the Community Manager developer portal in the same way as REST or SOAP APIs.

Akana offers a rich set of security features that can be applied to any API on the Akana API Platform in a number of ways: for example, through policies attached to the service, configuration settings, and custom workflow.

Additional security settings specific to GraphQL are also available: see Configuring GraphQL above.

Reference Information

Exchange Properties

If you have custom scripting or custom workflow in place, you can use exchange properties to manipulate how GraphQL requests will be processed. The following properties are available.

com.soa.message.EXCHANGE_STARTED_DATE
The start date. It can be read for activities such as logging time delays. Do not change this value.
Data type: java.util.Date.
http.requested.url
Target endpoint to send request to. Orchestration workflows can adjust this value to control where incoming requests are forwarded.
http.version
The HTTP version to use for downstream service requests. 1.0, 1.1, or 2.0.
http.method
The HTTP method to use when forwarding requests to downstream services. GET or POST are excepted. Defaults to the incoming HTTP method.