DEV Community: Gravitee

Write your own policy with Gravitee.io API Management 4.0.0

Yann Tavernier — Thu, 28 Sep 2023 05:17:35 +0000

The vast world of APIs is constantly evolving. This can be seen with the recent rise in popularity of event-driven architecture connected through modern event brokers (Kafka, Solace, etc.) and asynchronous web APIs. This transition from traditional, REST-dominated architectures with synchronous request-response style communication to mixed architectures dependent on both synchronous and asynchronous protocols requires a modern and versatile API Management solution: enter Gravitee API Management (APIM).

As of Gravitee 4.0, APIM is an event-native API solution. This means Gravitee natively supports asynchronous web APIs and event brokers while still fully supporting synchronous request/response style APIs in a centralized control plane. Regardless of protocol, Gravitee can modify the behavior of the request or response through policies. Gravitee policies fall into several functional categories: security, transformation, restrictions, performance, routing, and monitoring & testing.

Gravitee offers both a free Community Edition and paid Enterprise Edition of our platform. To learn more about what features are available in each edition, check out our brand-new documentation site!

Gravitee’s protocol and policy support are powered through an extensible plugin system. So while there is built-in support for a number of protocols, policies (and more), the plugin system allows anyone to add new policies or even entrypoints/endpoints to APIM.

Yes… I know, this opens up a brave new world of seemingly endless possibilities. But how to get started?

In this article, I’ll teach you how to write your own custom policy using the plugin system, but first, a few housekeeping items.

🙋‍♂️ Who am I ?

I am Yann Tavernier and I am a developer on the amazing APIM team at Gravitee. I'm delighted to walk you through the creation of a policy and how to efficiently test it!

📝 Prerequisites

Your favorite Java IDE
JDK 17
Maven 3.8

👨‍🏫 About Gravitee

If you want more information about the Gravitee platform, head over to the Gravitee Essentials section of our documentation site.

🔑 Key APIM components and concepts

Before we start looking at Policy creation and testing, let's provide an overview of all of the key concepts and components that we'll be using in this blog.

Key components

APIM is the API Management solution created by Gravitee.
APIM Gateway: A reverse proxy layer that brokers, secures, and hardens access to APIs and data streams. It is the component of APIM responsible for handling requests from customers.
APIM Management API (mAPI): A REST API used to configure and manage APIs and various Gravitee resources.
APIM Console: A graphical user interface to configure Gateways, create APIs, design policies, and publish documentation. Every action in the APIM Management Console is tied directly to the mAPI.

Key concepts

API Publisher is a role type for APIM, representing the user of the company in charge of designing and publishing the APIs.
API is the representation of your backend inside APIM, and is composed of elements such as documentation, users, design, properties, etc.
Plan is the access and service layer on top of an API for consumer Applications. Consumer Applications need to subscribe to a plan to be able to consume an API.
Plugin is a component that provide additional functionality to the Gravitee ecosystem.
Policy is a service or action that can be executed on an API request or response to perform checks, transformation or other services to it. As well as out of the box policies, you can also create your own. The functionality of the policy is enabled through plugins.

If you want more information about Gravitee, read this awesome Dev Guide! Even better, this guide is directly available on our community forum, so you can ask all your questions.

What is a policy?

As mentioned earlier, a policy is essentially a service or action executed on a request, response or a message to perform things like transformations, rate limits, routing, monitoring & testing, etc.

Technically speaking, a policy is nothing more than a piece of Java code consuming an execution context and returning a Completable (see here).

Let's take a look at the interface (Javadoc removed for readability purpose):

public interface Policy {

    String id();

    default Completable onRequest(final HttpExecutionContext ctx) {
        return Completable.complete();
    }

    default Completable onResponse(final HttpExecutionContext ctx) {
        return Completable.complete();
    }

    default Completable onMessageRequest(final MessageExecutionContext ctx) {
        return Completable.complete();
    }

    default Completable onMessageResponse(final MessageExecutionContext ctx) {
        return Completable.complete();
    }
}

⚠️ Note that, as we are in the reactive world, the policy implementation is used to build a reactive chain and this chain should only be executed when the Gateway subscribes to the policy. In short, this means your policy code must be written in the context of a Completable object creation.

Here is a good example 💪

Completable onRequest(final HttpExecutionContext ctx) {
    return Completable.fromRunnable(() -> request.headers().set("X-DummyHeader", "dummy"));
}

And a bad one 💥 (In the following example, the code will be executed before the subscription takes place which can have unintended side effects)

Completable onRequest(final HttpExecutionContext ctx) {
    request.headers().set("X-DummyHeader", "dummy"); // 💥 Not to do
    return Completable.complete();
}

👩‍💻 Creating our own policy

The best way to learn is by doing. I will talk you through all the steps needed to create a fully functional custom policy. Let's create a 🍕 Pizza Factory policy.

The goal of this policy is quite simple. It will use the request headers and payload to transform the request into a JSON pizza object. This will be duplicated on the response phase to return the created pizza Object to the user.

The policy will be configurable:

Users can configure the crust and the sauce.
To keep consumers of the pizza safe, we will add a toggle to forbid the word "pineapple" or "🍍". If the API request contains pineapple, then the Gateway will return a 406 Not Acceptable, else 500 Internal Server Error.

💡 In a more realistic policy, we would have the policy return a 400 Bad Request to follow standard HTTP error message semantics.

✅ Some acceptance criteria

Headers must follow this format: X-pizza-topping: #value#. You can use it multiple times to add as many toppings as necessary.
Body must be an array of strings representing the toppings to add.
If no X-Pizza-Topping header is present and the body is empty, then a pizza object is not created and X-Pizza: No Pizza header is added.
If both X-Pizza-Topping header and body payload are present, then both are used to compose the pizza object.
If the body is not an array of strings, then it results in a 400 Bad Request.
The body of request or response will be replaced by the pizza object. We assume the content type will be application/json.

🧪 Initialize it!

To initialize your policy, simply fork or clone https://github.com/gravitee-io/gravitee-policy-template.
This repository contains the necessary structure and minimum files needed to create a policy. You may need to update some dependencies (in pom.xml) to be consistent with versions used by APIM.

Policies are written in Java and use Maven as the build tool.

Let's take a close look at the structure of the policy.

README.adoc is here to explain the purpose of your policy, how to use it and the error cases. 💡 This file is used in the Management Console UI of Gravitee APIM as in-app documentation for the users of the platform; therefore, take care to ensure that the README is clear and comprehensive.
pom.xml contains information about the project and configuration details used by Maven to build the project. This base comes with the minimal set of dependencies to develop and build your policy.
src/assembly is used by maven-assembly-plugin to generate the zip of the policy with the right structure. ⚠️ You do not need to modify this file.
src/main/java will contain the policy code
src/main/resources/plugin.properties is the manifest of the policy. It contains informations such as the policy's id, name and icon. For the Pizza Policy, plugin.properties file will look like this:

id=pizza-factory
name=Pizza
version=${project.version}
description=${project.description}
class=io.gravitee.policy.pizza.PizzaPolicy
type=policy
category=transformation
icon=pizza.svg

src/main/resources/schemas/schema-form.json is the representation of the configuration of your policy. It is used to generate the schema and validate the creation of a policy whether using the APIM Management UI or the Management API directly.
src/test/java and src/test/resources are here for testing purposes. Here, you can find a TemplatePolicyIntegrationTest test class that has already been implemented. We will discuss it in more detail later, but essentially, it allows for easy creation of unit tests to verify your policy behaves as expected. This is done by deploying an API using this policy on an in-memory Gateway and then calls the API to verify the response matches the expectation.

🚀 Let's develop it

I will not detail every step, but instead focus on the steps required to develop a policy in Gravitee.

📤 The request phase

Let's go into it. As a reminder, our policy aims to transform the body into a JSON pizza object depending on incoming request headers and payload.
We will modify the onRequest method in this way:

@Override
public Completable onRequest(HttpExecutionContext ctx) {
    return ctx.request().onBody(maybeBody -> doSomethingHere());
}

The HttpExecutionContext allows developers to access different objects tied to API transaction itself:

request(): allows access to the current request which provides accessors to headers, pathParameters, HTTP method, pathInfo, host, etc. It also provides methods to manipulate the body (onBody) or to interrupt the call (interruptWith).
response(): the same thing as request() except you don't have any request related information.
getAttribute(String attribute): allows you to manipulate an attribute that has been stored in the context of the API transaction.

💡 The onBody method lets you manipulates a Maybe<Buffer>. This can handle the uncertainty inherent in every API request: maybe the request has a body, maybe not.

🍕 Creating a pizza

First, we will create the core feature of our policy: the createPizza method. As inputs, it needs the incoming payload and headers, and will return a Buffer: our pizza object. As we extract the body and headers from the context object, we do not need to stay in the reactive programming style, we will see later how to do the link.

Our method would look like this:

private Buffer createPizza(Buffer body, HttpHeaders headers) throws IOException {
    final Set<String> toppings = extractToppings(body, headers);

    if (toppings.isEmpty()) {
        return Buffer.buffer();
    }
    verifyPineapple(toppings);

    final Buffer pizzaObject = createPizzaObject(toppings, headers);

    return pizzaObject;
}

Some information:

extractToppings(Buffer body, HttpHeaders headers) is responsible for the following:
- extracting the toppings from headers (X-Pizza-Topping)
- extracting the toppings from body. In this case, body must be a valid json array of strings, or else a NotStringArrayException will be thrown.
- returning the set of toppings extracted from body and headers.
If the list of toppings is empty, the pizza is not created and an empty buffer is returned.
Next, comes the pineapple case. If policy is configured to refuse pineapple, and toppings list contains pineapple or 🍍, then a PineappleForbiddenException would be thrown.
Finally, the method creates and returns a pizza object which is just the JSON representation of the pizza from the configured crust, sauce and extracted toppings. A PizzaProcessingException could be thrown in case of mapping issue.

This code is fairly straightforward and does not require any knowledge of reactive programming.

🍽️ Serving the pizza

However, the createPizza method now needs to be transformed. We have to integrate our createPizza method into the reactive chain.

The reactive world, and more precisely RxJava 3 in our case, does not directly manipulate Buffer, it manipulates reactive objects. Those objects implements the Reactive Pattern for different cases:

Single for a single value response
Maybe for a single value, no value or an exception
Completable for a deferred computation without any value, but only indication for completion or exception
Flowable to consume reactive dataflows
And many others.

Remember, our method returns a Buffer: an empty buffer if there are no toppings, or the pizza object as a buffer.
This is a perfect use case for the Maybe reactive object:

If there are no toppings, return Maybe.empty()
Else, return Maybe.just(pizzaObject)

The method now looks like this:

private Maybe<Buffer> createPizza(Buffer body, HttpHeaders headers) throws IOException {
    final Set<String> toppings = extractToppings(body, headers);

    if (toppings.isEmpty()) {
        return Maybe.empty();
    }
    verifyPineapple(toppings);

    final Buffer pizzaObject = createPizzaObject(toppings, headers);

    return Maybe.just(pizzaObject);
}

Now, we are able to use our method in a reactive way:

@Override
public Completable onRequest(HttpExecutionContext ctx) {
    return ctx
        .request()
        .onBody(maybeBody ->
            maybeBody
                // If no body, then use an empty buffer
                .defaultIfEmpty(Buffer.buffer())
                // Create a pizza from body and headers
                .flatMapMaybe(body -> createPizza(body, ctx.request().headers()))
                // If no pizza has been created, then handle the case
                .switchIfEmpty(handleNoPizza(ctx.request().headers()))
                // Manage errors
                .onErrorResumeNext(handleError(ctx, true))
        );
}

Let me provide some further explanation of these changes.

onBody lets us manipulate a Maybe<Buffer>. This body can indeed be empty if the user provides toppings only using headers.

The first step is to have something to manipulate. Using maybeBody.defaultIfEmpty(Buffer.buffer()) provides an empty buffer to be used in subsequent steps. If we've kept an empty maybe, then we could not continue to the next steps in the reactive chain. There must be something to compute.
Now, we have a Single<Buffer>. Thanks to the flatMapMaybe() operator, we can use the Buffer and return a Maybe object. That's exactly what we have done with Maybe<Buffer> createPizza(Buffer body, HttpHeaders header)
With the switchIfEmpty() operator, we can handle the case of an empty pizza, by adding a X-Pizza: not-created header with this method:

private static Maybe<Buffer> handleNoPizza(HttpHeaders headers) {
    return Maybe.fromCallable(() -> {
        headers.add(X_PIZZA_HEADER, NOT_CREATED);
        return Buffer.buffer();
    });
}

Finally, we handle the errors that might have ocurred during the process with the onErrorResumeNext() operator. Let's look at the error handling in more detail.

💥 Managing errors

The onErrorResumeNext() operator allows you to resume the flow with a Maybe object that is returned for a particular failure. In other words, it allows to properly manage the error cases that can occur in the reactive chain.

Our requirements were about returning particular HTTP status codes depending on whether we are in request or response phase, and provide details on the type of error:

REQUEST:
- PineappleForbiddenException: 406 - Not Acceptable
- All other exceptions: 400 - Bad Request
RESPONSE:
- All exceptions: 500 - Internal Server Error

The HttpExecutionContext contains an interesting method: interruptBodyWith(ExecutionFailure failure). It allows the developer to fail the current request/response flow with an ExecutionFailure object.
This objects can be configured with:

(required) the HTTP status code to return to the user
a message to be returned as the body
a key that can referenced by the Response Template feature of APIM
and some other features we won't dive into here

The error management code is pretty straightforward to write:

private Function<Throwable, Maybe<Buffer>> handleError(HttpExecutionContext ctx, boolean isOnRequest) {
    return err -> {
        log.warn("It was not possible to create the pizza because: {}", err.getMessage());
        if (isOnRequest && err instanceof PineappleForbiddenException) {
            return ctx.interruptBodyWith(
                new ExecutionFailure(HttpStatusCode.NOT_ACCEPTABLE_406).key(PIZZA_ERROR_KEY).message(err.getMessage())
            );
        }
        return ctx.interruptBodyWith(
            new ExecutionFailure(isOnRequest ? HttpStatusCode.BAD_REQUEST_400 : HttpStatusCode.INTERNAL_SERVER_ERROR_500)
                .key(PIZZA_ERROR_KEY)
                .message(err.getMessage())
        );
    };
}

🚦 Test your policy

Gravitee APIM comes with what we call the Gateway Testing SDK.

This library can be seen as a JUnit 5 extension which allow the developer to:

Write tests as regular JUnit 5 tests
Run an in-memory gateway (and configure it as needed)
Deploy inline plugins (directly from code)
Do real call against the gateway to verify it behaves as expected

In our present case, we will want to validate that if we call an API using the Pizza Factory Policy, then we have the expected behavior in term of returned object or error handling.

Some cases to be tested (on both request and response):

Should not create a pizza when no topping provided
Should create a pizza when toppings comes from headers
Should create a pizza when toppings comes from body
Should create a pizza when toppings comes from headers and body
Should not create a pizza when toppings contains pineapple and it's forbidden
...

Test preparation

APIs are deployed from a JSON definition. You can learn more about Gravitee's API definition here.

Here is the policy configuration portion of an API definition:

"request": [
        {
          "name": "Pizza Factory on request",
          "description": "Create your pizza from request headers!",
          "enabled": true,
          "policy": "pizza-factory",
          "configuration": {
            "crust": "Pan",
            "sauce": "TOMATO",
            "pineappleForbidden": false
          }
        }
      ],

This JSON string will be used to deploy the test API on the testing Gateway, and will allow us to call this API for testing.

Next, we need to create a test class. APIM team uses the IntegrationTest suffix to distinguish tests using the SDK from regular unit tests.

Here is the minimal code needed to do to run a test with the SDK:

@GatewayTest
@DeployApi("/apis/pizza-api.json")
class PizzaPolicyIntegrationTest extends AbstractPolicyTest<PizzaPolicy, PizzaPolicyConfiguration> {

    @Override
    public void configureEntrypoints(Map<String, EntrypointConnectorPlugin<?, ?>> entrypoints) {
        entrypoints.putIfAbsent("http-proxy", EntrypointBuilder.build("http-proxy", HttpProxyEntrypointConnectorFactory.class));
    }

    @Override
    public void configureEndpoints(Map<String, EndpointConnectorPlugin<?, ?>> endpoints) {
        endpoints.putIfAbsent("http-proxy", EndpointBuilder.build("http-proxy", HttpProxyEndpointConnectorFactory.class));
    }

    @Test
    void should_create_pizza_with_header_toppings_on_request(HttpClient httpClient) {
      // We will focus on the test case later
    }
}

@GatewayTest is a meta-annotation which marks the class as testable with the SDK. It will run the necessary extensions to run the Gateway and initialize components
@DeployApi deploys an API based on its definition. You can also pass an array of APIs to deploy, where each API must have a distinct name and entrypoint.
- Used at class level, it will deploy the APIs once for the Gateway instance, meaning all the methods annotated with @Test will be able to call those APIs.
- Used at method level, it will deploy the APIs for the lifetime of the test method and then it will be undeployed.
AbstractPolicyTest<PizzaPolicy, PizzaPolicyConfiguration is an abstract class allowing you to directly register your policy on the Gateway. You can also extends AbstractGatewayTest and register your policy thanks to AbstractGatewayTest#configurePolicies(Map<String PolicyPlugin policies)
configureEntrypoints(Map<String, EntrypointConnectorPlugin<?, ?>> entrypoints) and configureEndpoints(Map<String, EndpointConnectorPlugin<?, ?>> endpoints) allow the developer to register entrypoint and endpoint plugins. In this case, http-proxy connectors are registered so that the API can be deployed as a proxy api.

💡 You can learn more about the difference between Proxy and Message Gateway APIs here.

Writing a test

You may have noticed in the previous example that an HttpClient is injected as a parameter of the test method:

@Test
void should_create_pizza_with_header_toppings_on_request(HttpClient httpClient) {}

It is injected to make your life easier. An important thing to understand is that the Gateway is started on a random available port, and the same applies to the started Wiremock used as endpoint.

When deploying an API, the SDK will update the localhost:8080 endpoints with by the right port and thereby allowing requests to reach Wiremock.

The HttpClient, in the same way, is configured to reach directly to the Gateway on the right port.

So, we now want to test if a pizza is created from toppings provided as a header when the Pizza Policy is configured on request phase. API is configured to be reached on /test path and to contact a backend on /endpoint path.

Here is the code of the test, with comments:

@Test
@DisplayName("Should create pizza when toppings provided from headers")
void should_create_pizza_with_header_toppings_on_request(HttpClient httpClient) {
    // 1. Prepare wiremock endpoint to answer with a `200 - OK` and an empty body when `/endpoint` is reached
    wiremock.stubFor(get("/endpoint").willReturn(ok()));

    // 2. Use the HttpClient to call your deployed API, configured with `/test` as context-path
    httpClient
        .rxRequest(HttpMethod.GET, "/test")
        // 2.1 Send the request to the gateway, with toppings header: `x-pizza-topping:peperoni,cheddar`
        .flatMap(request -> request.putHeader(X_PIZZA_HEADER_TOPPING, List.<String>of("peperoni", "cheddar")).rxSend())
        // 2.2 Verify the response status is the expected one and return the body
       .flatMap(response -> {
            assertThat(response.statusCode()).isEqualTo(HttpStatusCode.OK_200);
            return response.body();
        })
        .test()
        .awaitDone(10, TimeUnit.SECONDS)
        // 2.3 Verify the call is complete, and that the body is an empty buffer   
        .assertComplete()
        .assertValue(Buffer.buffer())
        .assertNoErrors();

    // 3. Verify the wiremock endpoint has been called
    //    - on `/endpoint`
    //    - with header `x-pizza:created`
    //    - with the expected pizza object
    wiremock.verify(
        1,
        getRequestedFor(urlPathEqualTo("/endpoint"))
           .withHeader(X_PIZZA_HEADER, equalTo(CREATED))
           .withRequestBody(equalTo("{\"crust\":\"Pan\",\"sauce\":\"TOMATO\",\"toppings\":[\"peperoni\",\"cheddar\"]}"))
    );
}

🏆 That's it, you know how to test a policy! You just need to implements the other test cases.

You can find the README of the SDK here.

For more examples of tests, you can take a look here.

🍕 Use it!

Now, it's time to use your policy.
You first need to build the ZIP file that will be deployed on the Management API and on the Gateway of APIM.

Thankfully, this is quite simple. Just run mvn clean install. (The policy is preconfigured to apply a prettier check and to enforce code formatting. If you have any issues, you may need to manually run mvn prettier:write).

This generates a ZIP file containing all the necessary assets for the policy to be used by APIM. This ZIP file can be found in the target folder.

Deploying a plugin is as easy as copying the plugin archive into the dedicated directory. By default, you need to deploy the ZIP in ${GRAVITEE_HOME}/plugins (more information here).

⚠️ You need to restart the Management API and Gateway for the plugin to be loaded.

🤔 What about v2 APIs?

For existing users of Gravitee APIM, you probably have some "v2" APIs.
Those APIs were running with the legacy engine, and policies were written in a different format than what was shown in this blog.

Lucky for you, you can use policies written in 4.0.0 style with existing v2 APIs, 4.0 was designed with backward compatibility in mind. To do so, "v4 Emulation mode" must be enabled by setting the executionMode field of your API definition to: v4-emulation-engine.

💡 You can learn more about the different Gravitee execution engines, API definitions, and emulation mode here.

✅ To wrap up

In this blog, we just saw how to write, test and deploy a simple custom policy to explore the extensible nature of Gravitee APIM. You can find the complete policy on the Gravitee Pizza Policy repository.

If this blog inspired you to build your own policy, you can get started quickly by forking the Policy Template.

All are welcome to get involved in the Gravitee Community. From everything to submitting pull requests in the APIM repo to getting involved in our Gravitee Community Discourse, we'd love to have you join our vibrant community.

Please don't hesitate to ask for support on our community discourse 🤝, we are happy to help!

What is API Management and how it helps you get the most out of your APIs

lju-lazarevic — Thu, 16 Jun 2022 17:25:59 +0000

The explosion of APIs

We are witnessing a huge explosion of APIs, largely driven by a number of factors, including:

Breaking up the monolith - taking large applications with many services and breaking up those interdependencies into individual, easier to develop and manage standalone services
Faster innovation - understanding the data demand and providing APIs that support these demands, promoting fail fast and trialing proofs of concept
Resource sharing - democratizing data and services across departments in an organization

With this immense growth of APIs comes great opportunities, but also, there are some challenges as well.

The challenges of APIs

There are a number of challenges facing organizations as the number of APIs that they develop and deploy increase. Let’s take a look at some of them.

Discoverability
How do developers find these APIs? How do they discover what is available? Where can they locate the documentation? How do they subscribe to the APIs? Ultimately, what does that developer experience look like?

Security and performance
Do you really want to tightly couple authentication and authorization to each API, along with its business logic? How are you going to manage policies on who can access what? Are these policies on an API by API basis, or organizational wide? What about protecting the backend applications? How do you prevent excessive requests to them? What about managing caching and other policies that will not only protect your applications, but also improve performance.

Governance
How do ensure the processes around API design and creation are being followed? For example, are the naming conventions being followed? Are the right stakeholders involved? How are existing services and functions being used?

Monitoring and alerting
Who is using your APIs? How do you know when and where they’re being accessed? Are they being used at all?! Are your APIs and the systems behind them still responsive? How do you check for unusual or suspicious behavior?

Changing the mindset

So how do we address and support the rise of APIs?. First of all, we need to start thinking about APIs as a product. Historically, the attention would be focussed on building the application itself, and then addressing how the application would work with other ones would come last. Changing that mindset to thinking about the API as a product, and designing the API first brings a number of benefits. The journey starts with considering who is going to use the API, what services will it be providing access to, and so forth. This practice of putting the API development ahead of the rest of the application is called API First, which we will cover shortly.

Another element to support the rise of APIs is through API Management. API Management allows us to remove the complexity around API development, so that our concern is centered around the building of the API and the supporting business logic, and let something else deal with the security, the governance, the lifecycle management, and so forth.

API and Design First

API First introduces the mindset of treating your APIs as products. This involves considering the APIs to have equal importance as the application itself. They are viewed as the doorway to the products and services your project is going to provide, and become the first consideration. Regardless of what happens with the project, ultimately everything is going to be using the APIs, so the thinking starts there. It is the component that’s most likely to change if an application, ‘bottom-up approach’ is taken instead. API First allows us to get feedback from all of the key stakeholders, as well as iterating on designs quickly and getting buy-in. Once there is agreement from across the board, everything else can follow in turn.

However, API first is not designed first. There are subtle differences between Code First and Design First in the terms of API first. Code First delivers the API first, with all other activities based on consuming the API coming after. Design First seeks to get a consensus on the API contract, allowing for parallel development based on what the API will look like. My colleague Lorie Pisicchio goes into more detail on this, based on her fantastic blog, as well as a talk she did for API World 2021. Do check them out!

Introducing API Management

API management is a methodology to manage the complete lifecycle of APIs. As well as being a methodology, there are platforms and tools to assist in its application and governance.

There can sometimes be confusion between API Management and an API Gateway. An API Gateway brokers the connection between a client and the API and its backend. It will apply any policies on the request and response flows, such as rate limiting, throttling and transformation. API Management would, as part of the process, determine what policies should be applied, as well as maintaining the historical records of changes made as part of the API lifecycle.

A simple analogy would be as follows - imagine an automated rotating door (the API) between the outside and inside a building, housed within a frame with the mechanics (the API Gateway). The door may revolve at a certain speed (a throttling policy) along with other constraints, however the decision for what rate the door will rotate, and that there’s a rotating door rather than an automatic sliding door, or a hinged, manual door, as well as how it would be installed, and what processes are used to maintain it, was made at the time of building planning (API Management). A decision could be made to speed up or slow down the doors could be made (API Management), as well as whether to remove the doors completely and use a different type, including overseeing the removal and installation (API Management).

So let’s investigate what API Management offers us in terms of dealing with APIs. First of all, there's no point in having an API if a developer can't find it. API Management helps us to not only create APIs, but also publish the APIs and make them discoverable to developers, as well as providing the documentation and other associated information. We can also use information as the APIs are being subscribed and used to nurture the developer community, as well as understanding how they’re using them, getting their feedback, and ultimately, improving the developer experience.

API management also helps enforce the use of policies and controlling access to APIs. So we can deal with whether a client has been authorized or authenticated to use it.We can apply performance policies such as rate limiting and throttling to not only protect against malicious behavior, but to also look after the backend systems.

We can monitor and analyze how APIs are being used, if they’re being used, as well as checking on the health of our APIs. We can also proactively look out for unusual or suspicious behavior and act accordingly, triggering alerts as appropriate.

Last but not least, API management can help us with governance, for example company wide policies, naming conventions, design conventions and so forth.

All in all, API management relieves us from the infrastructure logistics involved in making APIs available, and allows us to apply our focus on the business logic contained within the API management itself. Let’s now have a look at an example API Management platform, Gravitee, an open source product.

Overview of an example API Management platform

Gravitee is a fully open source, low code, highly customisable API management platform, with a highly performant API gateway. It is a Java based product using the Vert.x framework. It uses the concepts of plugins to manage policies, including security, data transformation, protocol mediation, monitoring, authentication, performance and so forth. There are over 100 plugins available, and should you happen to not find the one you’re looking for, you can write your own.

Developer Portal

The developer portal is where developers can explore, research and subscribe to your APIs. They are able to try out the API's, read the documentation, as well as providing reviews and feedback.

API Console

This is where the API owner can manage the whole lifecycle of the API from design, deployment, policies to apply, API deprecation and disablement. They are also able to monitor API activity. There is also an API available for CI/CD deployments and other automation.

API Gateway

The Gateway is responsible for being the doorway between the client and the API. It will apply the policies as dictated by the API Console, and all of the rules applied will be deployed onto the Gateway by the Console.

If you’d like to have a go at getting the Gravitee APIM platform up and running on your local machine, this blog post provides you with step by step instructions.

Wrapping up

Hopefully, you now have a good overview of what API Management does, the difference between API Management and API Gateways, as well as the opportunity to get an example of an API Management platform that can support this practice.If you’ve got any questions about either Gravitee, or API Management in general, do reach out to us on our community forum.

Explaining API Management to your mom

Antoine Mouliere — Wed, 08 Jun 2022 08:21:15 +0000

In this blog post we’re going to cover what are all the parts of API Management using an example based on a restaurant. We all too often forget that not everybody is technically-minded, and sometimes it’s great to take a step back and find common language to explain certain terminology.

So what’s your job again?

Nice to meet you all, I’m Antoine, a Product Owner of the Gravitee.io API Management solution, you can find me on our community forum. One of the biggest challenges I’ve met so far is to answer my mom’s question, “What’s your job all about?”.

I guess my normal answer would be, “Product Owner of largest Open Source API Management mom. We’re creating software to build, monitor and secure APIs! Did I also mention it’s Open Source? Isn’t that awesome!?”.

However, that didn’t seem to convince her that much, nor did it help her understand what I'm doing with my day. But she’s my mom, so she loves me anyway and she’ll get along with “my son works in IT”. I’m looking for a change - I don’t want to fix printers anymore, and I guess my mom deserves to understand what I'm working on. A thought to consider, do we really understand our areas of expertise if we can’t even explain it to our mom, or a six-year old for that matter?

And so comes the tricky question: how do I explain what API management is to my mom? I’ve been trying to figure out some sort of approach. I’ve been:

Diving into my school archives to find relevant resources
Exploring howtocode.com
Looking at the basic tenets of IT, and so on.

Do I really want to give my mom a four-hours lecture on the basics of APIs? I’m not so sure. Does she want to listen to a four-hour lecture? Hmmm not sure either. Is this going to work with a six year old? Definitely not!

What’s needed is something that’s tangible, based on a real-life situation that can aptly describe the purpose of API Management. So, let’s run with the example of a restaurant - everyone can relate to a restaurant - even my two-year old son has mastered the art of ordering fries.

The restaurant analogy

Photo by Jeremy Bishop on Unsplash, and as you can see I’m not a designer ;)

Client/Customer - It’s rather funny that we use the same term in API Management! Coincidence - I don’t think so! The client application is what sends a request. How would they go about making their request? Are you going to a restaurant and asking for whatever you want? Most certainly not, you will ask for a menu.

The API Specification or definition is the equivalent of a menu in a restaurant. It contains a list of what you can order, and a description of what you can expect for each item.

The backend of your application is the equivalent of the restaurant’s kitchen. The kitchen will prepare your meal, dish it out and nicely present it on a plate, and with a bit of luck, give you exactly what you ordered. This is the backend’s responsibility - to provide you the information you need, apply any processing to the data, and maybe request more information from other sources. The kitchen would handle the food processing, for example freezing, defrosting, slicing, dicing and cooking. The kitchen may need to request more ingredients. All of this information and processing going on, you, as a client or customer, do not need to know about, nor should you care about it for you to receive your ordered dish!

So we now have a customer (client), a menu (API specification) and a kitchen (backend system). We are missing one key element here. How does the kitchen know what you want? Sure, you could go into the kitchen yourself and directly ask the chef, but he’s nervous, and doesn’t really want to be speaking to lots of people during the dinner rush hour. Also, it’s not particularly hygienic to have people coming into a kitchen, nor is it practical for 30-odd patrons to walk in, shouting out their preferred order. So, how do we deal with taking the order from the party of 10 who’ve just turned up, as well as trying to keep the children across the room not crying out for as long as possible? The waiter!

Waiters are the equivalent of APIs. The waiter goes to the customer to get their order, and brings it to them. They will also:

Prevent overconsumption (in my opinion, two dishes are plenty)
Offer adaptations if something is unavailable on the menu (we’re out of smoked salmon, but the smoked trout is an excellent alternative)
Adapt the request timing and arrival in specific cases (let me bring some bread to your kids right now)

When the dishes are ready, they’ll also provide the appropriate cutlery for the meals, as well as delivering an overall expected experience. A waiter works very much in a similar way to APIs between your requests (the order off the menu) and the responses (the meals delivered to your table). There are a number of things that happen when you make requests and responses (called policies in API speak), such as:

Help secure your API calls (sorry, you’ve had enough to drink)
Apply data transformation (let me cut up the meal for your child)
Get some more information in order that the backend can do its stuff (do you have any allergies the kitchen should be aware of?)
Processing a response (you’ve ordered the soup, I’ll bring a spoon)

How do APIs know how to handle these cases? Sure, there are common topics - security, data transformation for example, but how do we deal with specific organization policy? Let’s get back to our restaurant example. There are many common tasks (taking orders and delivering them), but the restaurant may have some specific policies to handle queues, both of customers waiting to get in, and the orders themselves, giving priority to certain orders, or perhaps just having certain ground rules that need to be applied to the restaurant in general.

API Management is the equivalent of our restaurant manager, or Maitre d’. The manager will define how the waiters (APIs) will work between the kitchen (backend) and the customers (clients). The manager can also analyze customer flow (monitor global traffic) and how everything is being handled. They will follow up on all the orders, as well as managing how customers are billed for their meal (API monetisation - If you’d like to know more, check out this post by our dear Linus, VP of Product). In addition, API Management can take a more holistic and bigger picture view of what’s going on in the restaurant, and look to make the waiters (APIs) jobs easier. For example:

Hire a bouncer at the door to check if patrons are too drunk to be served alcohol (gateway security and/or integrate access management, e.g. Gravitee AM)
Provide standard policy all waiters follow in relation to hungry children (gateway caching)
Raise awareness of what’s not currently available on the menu and suggested alternatives ahead of time (gateway dynamic rerouting)

Summary

Drawing from our restaurant analogy, in summary:

Restaurant - our system architecture
Customer - the client application
Menu - the API definition
Kitchen - the backend application/service
Waiter - the API
Restaurant manager/Maitre d’ - the API Management system

We’ve covered in this post how i would explain my job to my mom, and I hope if you’re in a similar tech role such as development, architecture, marketing and UX, you’ll appreciate the importance of being able to find a common vocabulary to explain our background, our concepts, our jokes, and ultimately our culture. It is a lot harder to work with each other if we’re not able to share and understand each other. I feel that, as a product owner/manager/team, we’re the bridge (or should I say, the gateway... hmmm hmmm API Management joke) between people.

Final thoughts

In my scrum team, we talk all day long about gateways, proxies, virtual hosts, processors, reactive development, fixing printers (haha, no chance!) and all those weird and wonderful terms. Can you imagine the faces of our User Experience team when we initially explained to them that we need a new user interface for virtual hosting? It goes the same way when you’re helping users - what are they trying to achieve? It matters not that they’ve got an issue with a specific protocol setting (bugs outstanding), what I really want to know is why they're using the product in this way.

What’s the best way to achieve this outcome? The best advice I've seen so far is to act like a six-year old. Keep asking why. Why? Why? Why? It forces you to really understand what is behind the surface - the 90% of the iceberg, and avoid misunderstanding. Don’t assume that your explanation is simple or straightforward. We all have different backgrounds and you want to make sure they have the same understanding of the concept as you do. If you can explain something to a six-year old, that means you really know your stuff!

Be a six-year old!

Troubleshoot your APIs with Debug Mode

Yann Tavernier — Fri, 29 Apr 2022 08:31:06 +0000

If you're regularly working with APIs, you'll know the struggles of ensuring that they're secured, protected and managed, as well as building out the core functionality.

If you haven't already, you'll want to check out API Management. In essence,

API management is the process of creating and publishing web application programming interfaces (APIs), enforcing their usage policies, controlling access, nurturing the subscriber community, collecting and analyzing usage statistics, and reporting on performance. API Management components provide mechanisms and tools to support developer and subscriber communities

(see on Wikipedia).

Using the open source Gravitee.io API Management platform (GitHub repo) allows you to create, design and manage the lifecycle of your APIs. With many rich and powerful policies available, you have a huge array of tools and techniques to superpower your APIs, such as:

Check authentication and manage other security aspects
Transform headers
Protocol mediation
Protect your backends against malicious and accidental traffic spikes

But sometimes, your designs become so complex that it is almost impossible to know where design and configuration problems occur when they pop up. Don’t panic, Debug Mode is here to the rescue. Debug Mode is a feature that unleashes the power of API Publisher, allowing you to design an API, (shadow) deploy it (don’t worry, we’ll explain what shadow deployment is later on), and understand exactly through which policies have been applied to the API call.

In this blog post, we are going to put ourselves in the shoes of an API publisher, looking at an API displaying some weird behaviors. We will walk through a simple example of an API, and show you not only how to use Debug Mode, but also how it works under the hood.

🙋‍♂️ Who am I ?

I am Yann Tavernier and I am a developer in the amazing APIM team. I had the opportunity to work on Debug Mode, and I’m delighted to walk you through and explain this feature!

🔑 Key concepts and components

Before we start looking at Debug Mode, let’s provide an overview of all of the key concepts and components that we’ll be using in this blog.

Key components:

APIM is the API Management solution made by Gravitee.io.
Gateway is the component of APIM responsible for handling requests from customers. As well acting as the proxy for APIs, it will also apply transformation, checks, rate limiting, and so forth on incoming requests and outgoing responses.

Key concepts:

API Publisher is a role type for APIM, representing the user of the company in charge of designing and publishing the APIs.
API is the representation of your backend inside APIM, and is composed of elements such as documentation, users, design, properties, etc.
Plan is the access and service layer on top of an API for consumer Applications. Consumer Applications need to subscribe to a plan to be able to consume an API.
Policy is a service or action that can be executed on an API request or response to perform checks, transformation or other services to it. As well as out of the box policies, you can also create your own.

🎬 Introducing our scenario

We are now going to introduce our simple scenario to walk through how to use Debug Mode.

All our examples will be done on a local installation. You can use this command to run APIM 3.17 with docker-compose:
cd /tmp && mkdir -p apim && cd apim && curl -L https://raw.githubusercontent.com/gravitee-io/gravitee-docker/master/apim/3.x/docker-compose.yml -o "docker-compose.yml" && export APIM_VERSION=3.17.1 && docker-compose down -v && docker-compose pull && docker-compose up

To access the console, go to the following address: http://localhost:8084

The default credentials are:

Login: admin
Password: admin

If you are interested in a more detailed guide, you can check this awesome blog from Ljubica Lazarevic!

We will rely on an API called Library backend. You can import it thanks to its API definition here.

This backend will be accessible on http://localhost:8082/library-backend and return mocked dataset:

{
   "books": [
       {
           "title": "A tale of two cities",
           "author": "Charles Dickens",
           "_internalReference": "gio_b1"
       },
       {
           "title": "The Lord of the Rings",
           "author": "J.R.R Tolkien",
           "_internalReference": "gio_b2"
       },
       {
           "title": "The Hitchhiker's Guide to the Galaxy",
           "author": "Douglas Adams",
           "_internalReference": "gio_b3"
       }
   ]
}

We will analyze this dataset later.

As an API Publisher, I want to design a “Library” API to access my Library backend.
You can create it following the documentation and follow this guide step by step or you can directly import the resulting API Definition.
First of all, I need to choose the type of plan to use for my API. We will choose two plans: a Keyless plan, called Free, and an API-Key one, called Premium.

Let’s firstly design the Free plan. This plan allows anybody to reach our API. To protect our backend systems, as well as improve performance, we want to manage the amount of traffic that will hit our API with this plan. We will limit the access thanks to the Rate Limit policy. One thing to note - as this is a free plan, consuming applications do not need to create a subscription.

As the API is going to be publicly accessible, we will want to hide away some private data in the response, the _internalReference field. To do this, we’re going to use the JSON to JSON Transformation policy.

Here is the configuration of JsonToJson Policy. Its purpose is to remove the _internalReference field in the array of books:

[
  {
    "operation": "remove",
    "spec": {
      "books": {
        "*": {
          "_internalReference": ""
        }
      }
    }
  }
]

Let’s deploy the API (you can do this by syncing the API when prompted) and call it with a cURL:
Calling curl http://localhost:8082/library will output:

{
   "books": [
       {
           "title": "A tale of two cities",
           "author": "Charles Dickens"
       },
       {
           "title": "The Lord of the Rings",
           "author": "J.R.R Tolkien"
       },
       {
           "title": "The Hitchhiker's Guide to the Galaxy",
           "author": "Douglas Adams"
       }
   ]
}

We have successfully hidden away the sensitive, internal data that was being exposed by the API. However, our developer teams may well need access to that data for testing purposes. So what we will do now is create an Internal, API-Key plan, to allow authorized access to the data.It works by verifying the API key that is passed as a header or query parameter, and is linked to an application that has subscribed to the API. You can find out more in the documentation on how to set this up.

Remember, the _internalReference removal was done on the Freemium plan. Here, with the Internal plan, we keep the original data. We will use this opportunity to use the Assign Attributes policy to add an internal attribute in the context. This attribute will be the concatenation of the application’s ID followed by “-internal” and accessible through the “internal” key.

To do that, we configured the Assign Attribute policy to add an internal attribute with the following value: {#context.attributes["application"]}-internal.

Now, calling the API with an API Key with curl http://locahost:8082/library?api-key=7cc755d1-378b-4099-9650-9ee9330be55c will output:

{
   "books": [
       {
           "title": "A tale of two cities",
           "author": "Charles Dickens",
           "_internalReference": "gio_b1"
       },
       {
           "title": "The Lord of the Rings",
           "author": "J.R.R Tolkien",
           "_internalReference": "gio_b2"
       },
       {
           "title": "The Hitchhiker's Guide to the Galaxy",
           "author": "Douglas Adams",
           "_internalReference": "gio_b3"
       }
   ]
}

NOTE: You may have noticed that we cannot see the attribute we set. In fact, the attribute only lives inside the API Gateway for the time of the call. This is a behavior of the policy we are using, and it is internal to the gateway.

Finally, we will create a flow on the API using the JSON to JSON transformation again to apply discounts to a book based on certain conditions.

The discount will be applied if the response is either:

Request is done with Header - “X-Library-Discount”:“discount percentage”
Attribute “internal” is not empty.

By default, the discount value will be the value of the X-Library-Discount header, or 10 percent by default.

To achieve that, we will firstly configure the condition of the policy:
{(#request.headeers['X-Library-Discount'] != null && #request.headers['X-Library-Discount'].size() > 0) || {#context.attributes['internal'] != null}}

Then, we will use this configuration for Json to Json Policy:

[
 {
   "operation": "shift",
   "spec": {
     "*": "&"
    }
 },
 {
   "operation": "default",
   "spec": {
     "discount": "{#request.headers['X-Library-Discount'] != null ? #request.headers['X-Library-Discount'][0] : 10}%"
    }
 }
]

Calling the API with curl http://localhost:8082/library?api-key=7cc755d1-378b-4099-9650-9ee9330be55c will output:

{
    "message":"Request failed unintentionally",
    "http_status_code":500
}

We have some issues with our last flow, but what happened? It’s hard to say by just using cURL or Postman. As the API design complexity increases, the risk of problems also increases. How can we avoid deploying our API to our users until we’ve solved all of the outstanding issues?

The APIM team created the new Debug Mode to solve this exact challenge.

💥 Here comes the Debug Mode!

The Debug Mode feature provides a way to have a global understanding and overview of what happens inside the gateway. With this feature, we are now able to send a request using our HTTP client, and see exactly which policies have been executed, with their inputs and outputs.

In the following screenshot, you can see an example of a request flow being examined using the Debug Mode:

The request is using the same API key as before, and we can see the Response ended in “500 - Internal Server Error”.

Let’s take a look at what the Debug Mode feature is showing us. The first important element of this feature is the timeline. It represents each policy that was run, shaped as a card. A card is composed of several elements:

The name of the policy (e.g. Assign Attributes)
Its stage (either: platform, security, plan, api) and scope (either: headers, body): Plan > Header
Its execution time (e.g. 0.227ms)

It represents the real order of execution of your policies, which may have changed from your initial design. You may notice that the execution could be different from what you expected!

If you’re a regular user of Gravitee, you are probably used to configuring policies and choosing one of the following scopes: REQUEST, REQUEST_CONTENT, RESPONSE, RESPONSE_CONTENT. For REQUEST and RESPONSE scopes, policy execution has no view or modification access on the content, contrary to REQUEST_CONTENT and RESPONSE_CONTENT.

We will not deep dive into this topic, but an important thing to note is that the gateway will first execute the header policies (REQUEST / RESPONSE) and then the content policies (REQUEST_CONTENT / RESPONSE_CONTENT).

Let’s click on the card to explore what information it provides.

Thanks to this differential view (we will call it a “diff”), we now can see and understand how the Assign Attributes works: it adds an attribute in the Attribute object of the internal context of the call.

So now, why did our request fail? Let’s scroll the timeline and find the failing policy.

Here it is! We can see two icons appearing on our Json to Json Transformation card. Looking at the Inspector, we can see it occurring on Api > Body.

IF… means the policy is conditional: it is executed only if the condition is evaluated to true.
! means the policy has an error

Looking at the diff, we can see the error message: “Request failed unintentionally”. This is what we saw and caught during the request processing. Unfortunately, in this case, it’s not very helpful.

The interesting thing, however, is the Condition block:

We can see that the condition is invalid. Reading the condition once more, it looks like we configured our policy using request.headeers instead of request.headers.

🛠 How does Debug Mode work ?

So how exactly does Debug Mode work? Let’s take a look under the hood.

When you send your Debug Request, the API Gateway detects the event, and it starts its processing.
It will deploy your current API in a particular state we call “Shadow Deployment”. This just means that the API is deployed, but not accessible to the public. This deployment is only used by Debug Mode, meaning there is no risk of your customers (or any other users!) accessing this version of your API!

You don’t need to deploy your API the regular way to be able to debug it. This can be really useful when you are doing some tests to find good tuning for a policy.

Let’s see it how it works:

You send your request to the Debug Mode request form.
- API Management will then create a Debug Event and store in to the database
- The event’s ID is returned to the user
- Then, the Console UI will poll regularly from APIM REST API until the event status is “SUCCESS”.
The Gateway will regularly sync with the database to check if there are some events with the status “TO_DEBUG”
When an event is found, we deploy our API in shadow mode. It implies two things:
- This API is not accessible for any user, only by the Debug Mode and only for the lifetime of the Debug session.
- This API is built with a particular encapsulation, providing the ability to store the execution information during all the lifecycle of the API.
An internal HTTP call with the content of the user's debug request is made to this API. It has the advantage of exactly replicating what would happen if you tried to call your API with cURL or Postman.
The gateway will process your request and transform data based on the configured policies, as usual. The only difference with a regular deployment is that information about headers, payload, context will be stored in the Debug context
Once the request is finished, the API is undeployed, and debug information is saved to the event.
Finally, the result is displayed to the user in the Console UI.

👨‍💻 Back to business

As we said earlier, the condition was misspelled, so we have now fixed request.headeers to request.headers in the JSON To JSON policy.

Let’s do the call once again in debug mode:

The response is 200 - OK, and we can see the discount applied in the response body.

Debug Mode can also tell us if a policy is not executing due to an unmet condition.
If we do not call the API with an api-key or X-Library-Discount, this JSON to JSON policy will not be applied, as you can see in the timeline:

📝 Wrap up

We’ve just done a simple example of a failing API with policy issues, and how to troubleshoot it with Debug Mode. We were able to see and step through the flows to understand what was really happening and what was causing the problem. We have also looked at how exactly Debug Mode works under the hood.

We would love to hear your feedback, and how you’re getting on with Debug Mode. If the topic interests you and you have questions, do not hesitate to join our community forum. The team will be happy to discuss it with you!