| description |
|---|
This article covers criticial Gravitee API creation concepts |
API consumers call or subscribe to Gateway APIs to the retrieve data, functionality, etc., exposed by backend APIs. Gravitee supports two types of Gateway APIs: v2 and v4. These are based on the Gravitee v2 API defintion and Gravitee v4 API definition, respectively.
{% hint style="info" %} Future efforts and innovation will focus on the v4 API definition., but v2 API documentation will be available while the v2 API definition is supported. {% endhint %}
The critical v4 API creation concepts are entrypoints, endpoints, and backend exposure methods.
When creating v4 APIs, you will need to define your Gateway entrypoints and endpoints. These are:
- Gateway entrypoints: The protocol and configuration by which the API consumer accesses the Gateway API. This essentially defines how the backend API is exposed through the Gateway.
- Gateway endpoints: The protocol and configuration by which the Gateway API will fetch data from, or post data to, the backend API.
For example, if you wanted to make a Kafka topic consumable over WebSockets, you would choose the WebSockets entrypoint and Kafka endpoint. If you wanted to expose a backend REST API as a Gateway REST API (i.e., a "pure" REST API use case), your entrypoint would be your context path (the URL location of your Gateway API) and the endpoint would be your target URL (the URL for the backend resource that you want to expose).
When creating Gateway APIs in Gravitee, you need to define the "type" or method of exposing your backend resources: Proxy upstream protocol or Introspect messages from event-driven backend. The architecture that you choose impacts which entrypoints and endpoints are available:
{% tabs %} {% tab title="Proxy upstream protocol" %}
- Entrypoints: Context path that supports REST, GraphQL, gRPC, and WebSocket Gateway APIs (policies cannot be applied at the WebSocket message-level using this exposure method)
- Endpoints: REST, SOAP, WebSocket Server, gRPC, GraphQL {% endtab %}
{% tab title="Introspect messages" %}
- Entrypoints: HTTP GET, HTTP POST, WebSocket, Webhook, Server-sent events
- Endpoints: Kafka (including Confluent-managed Kafka), Solace (contact us for the required Solace-specific plugin), MQTT
When choosing the message-based architecture, you can combine any supported entrypoint with any supported endpoint. For example, you could expose a Kafka topic as a REST API using HTTP GET, as a WebSocket API, as an SSE API, etc. {% endtab %} {% endtabs %}
In addition to message introspection, Gravitee offers both HTTP and TCP proxy support. The high-level characteristics of these APIs are summarized below:
{% tabs %} {% tab title="HTTP proxy" %}
- Traditional proxy APIs
- Use synchronous HTTP requests
- Support transformation to enable traffic shaping, analytics, and the application of policies {% endtab %}
{% tab title="TCP proxy" %}
- Can proxy any backend protocol that accepts TCP socket connections and can send data over the wire
- Raw TCP packets are transmitted in their native protocol format without transformation or introspection
- Traffic shaping is unavailable
- The types of policies and analytics that can be performed in the control plane are limited {% endtab %}
{% tab title="Message introspection" %}
- Protocol mediation is performed on incoming data streams
- Payloads are reformulated to be consumable by HTTP
- Support transformation and introspection to enable traffic shaping, analytics, and the application of policies {% endtab %} {% endtabs %}
Gravitee's v4 API definition offers support for a variety of API styles, event brokers, and communication patterns, as detailed below:
| Style/broker/pattern | What Gravitee can do |
|---|---|
| REST API |
|
| SOAP API | Expose backend SOAP web services as Gateway REST APIs |
| WebSocket APIs |
|
| Webhook | Gravitee can expose Kafka, Confluent, Solace, and MQTT backend data sources over a Webhook callback URL. This allows your API consumers to subscribe to a Gateway Webhook API and then retrieve events and messages from these backend data sources in real-time via the Webhook subscription. |
| Server-sent events (SSE) | Gravitee can expose Kafka, Confluent, Solace, and MQTT backend data sources over an SSE API. This allows your API consumers to subscribe to a Gateway SSE API and then retrieve events and messages from these backend data sources in real-time via the SSE API. |
| Kafka | The Gravitee Gateway can establish a persistent connection with a backend Kafka topic as a data source, allowing the Gateway to expose messages streamed from the Kafka topic to consumers via:
|
| Confluent | The Gravitee Gateway can establish a persistent connection with a backend Confluent resource as a data source, allowing the Gateway to expose messages streamed from the Confluent resource to consumers via:
|
| Solace | The Gravitee Gateway can establish a persistent connection with a backend Solace resource as a data source, allowing the Gateway to expose messages streamed from Solace to consumers via:
|
| MQTT | The Gravitee Gateway can establish a persistent connection with a backend MQTT broker (as long as that MQTT broker is running MQTT 5) as a data source, allowing the Gateway to expose messages streamed from the MQTT broker to consumers via:
|
{% hint style="warning" %} Limitations
v4 APIs currently do not support Gravitee Debug mode {% endhint %}
The v2 API definition hinges on the following:
- Endpoints refer to the final backend target or data source of a request
- There is no concept of entrypoints
Because there is no decoupling of entrypoints and endpoints, v2 APIs do not support protocol mediation between event brokers and messaging services. When creating v2 APIs, you are limited to proxying backend APIs that communicate over HTTP by exposing Gateway APIs that communicate over HTTP. Policy enforcement at the request/response levels is fully supported, but there is no support for message-level policies.