Getting Up and Running with Apiman

If you navigate to the “downloads” page, you’ll see:

Download the WildFly distribution.

Let’s take a look at the contents of the WildFly Overlay.

There are three main directories in the WildFly Overlay:

The Apiman directory - This directory contains configuration data specific to Apiman such as the DDL (Data Description Language) files that define database schemas used by Apiman, JSON files that define policy and security settings, and a quickstart example program that we will use as an example API. The Apiman directory is a new directory that is created when you unzip the WildFly Overlay file.

The top level directories in the Apiman directory look like this:

The modules directory - This directory contains configuration files, including Keycloak (URL) configuration files that are added to the WildFly server for Apiman. These files are added to the WildFly “standalone” server configuration.

The top levels in this directory look like this:

The deployments directory - this directory contains the Apiman API Gateway, back end APIs, and Apiman Management UI, packaged as .war files.

By unzipping the WildFly Overlay file, these .war files are deployed to the WildFly server.

The top levels in this directory look like this:

Make a mental note of these Apiman deployment files. We’ll see them again in a few minutes.

The steps you follow are:

The commands that you will execute to install the server will look something like this:

Before we move on, we have one server administration task to perform. We have to create a server user, so that we can log onto the server administrative console. This is necessary as WildFly does not come pre-installed with any users.

To create a new server user, navigate to this directory:

And execute this script:

When you are prompted for the type of user to create, select Management User:

After you define a username and password, for the remainder of the prompts, you can safely take the default values, or select “yes” to complete the creation of a user account.

Details on the administration of a WildFly server, including user management, are out of scope for this book as our focus is Apiman. If you are interested in learning more about WildFly server administration, refer to the WildFly Server Administration Guide.

To start the WildFly server, navigate back to the directory into which you installed the server, execute these commands:

When the server starts, it will write logging messages (a lot of messages!) to the screen.

When you see some messages that look like this, you’ll know that the server is up and running with Apiman installed:

Congratulations! Your WildFly server is up and running with Apiman installed!

Or is it?

Let’s take a quick look at how we can be sure that the server installation was correct. To do this, we’ll look in two places.

First, we’ll look at the WildFly Server Administrative Console.

Remember the user account that we created? We’ll use it now. To access the WildFly Server Administrative Console, open up a browser, and navigate to: localhost:8080

This page will be displayed:

When you select the Administration Console selection, you will be prompted for the username and password:

Enter the username and password for the user that you defined (for this example, we used the very unimaginative and insecure username “admin”) and you will be brought to the WildFly Server Administration Console:

If you then select the “Deployments” tab at the top of the page, you’ll see the applications deployed to the server. This is where you should see the Apiman deployments for the APIs, Gateway, and Management UI:

If you don’t see the Apiman deployments, don’t panic, but something went wrong with the installation.

The most common reason for the Apiman deployments to be missing is that you unzipped the Apiman overlay .zip file into a different directory from the WildFly server. The overlay must be unzipped over an installed WildFly server.

You can confirm that this is what happened by looking in the WildFly server’s deployment directory here: wildfly-23.0.2.Final/standalone/deployments

If you look in this directory, you should see these files (the presence of files with the “.deployed” suffix indicates that the corresponding file was deployed successfully):

So, if you don’t see the Apiman deployments, stop the server and start the installation over.

Be careful to unzip the Apiman overlay file directly over the directory created when you unzipped the WildFly server .zip file.

The second place we’ll look for evidence that the installation was successful is the WildFly server’s server.log file.

The WildFly server’s server.log file is created when the server is started. All the information that is displayed on the screen when you started the server is also written to the log file.

The level of detail written to the console and the log file is configurable. You can read more about configuring WildFly logging on the WildFly Administrator’s Guide.

You can find the WildFly server file in: wildfly-23.0.2.Final/standalone/log/server.log

The WildFly server log file can be quite large as the server will append more logging statements to it over time.

While you can certainly read the entire file anytime you want, we’ll focus on some highlights related to ensuring that the server started cleanly. An obvious first step is to search the file for logging statements written at the ERROR level. If the file does not contain any errors, you can look for statements that look like this to confirm that the server started cleanly:

That’s right, it’s the same Apiman deployment files. If you see statements like these, and there are no ERROR statements, then you should be able to safely access the WildFly Administration console.

There’s just more point we should cover before moving on.

While the server may be up and running, it’s not really configured for production use. As a convenience, when you install Apiman, it is preconfigured with a default administrator account. The username for this account is admin and the password is admin123! - not exactly a mission critical level of security!

If this were a production server, the first thing that we’d do is to change the default Apiman admin username and password. Apiman is configured by default to use Keycloak for password security and user management. Also, the default database used by Apiman to store contract and API information is the H2 in-memory database.

For a production server, you’d want to reconfigure this to use a production database. We’ll cover Apiman server security and production configuration settings in later chapters.

The source code for the example service is contained in a git repo (git-scm.com) hosted at GitHub (github.com/apiman). To download a copy of the example service, navigate to the directory in which you want to build the service and execute this git command:

git clone git@github.com:apiman/apiman-quickstarts.git

As the source code is downloading, you’ll see output that looks like this:

The source code for the example API is provided in the wildfly-23.0.2.Final/apiman/quickstarts directory.

The echo-API quickstart includes these files:

And, after the download is complete, you’ll see a populated directory tree that looks like this:

As we mentioned earlier, the example API is very simple. The only action that the API performs is to echo back in responses the metadata in the REST requests that it receives.

Maven is used to build the API. To build the API into a deployable .war file, navigate to the directory into which you downloaded the API example:

And then execute this maven command:

As the API is being built into a .war file, you’ll see output that looks like this:

If you look closely, near the end of the output, you’ll see the location of the .war file:

To deploy the API, we can copy the .war file to our WildFly server’s deployments directory. After you copy the API’s .war file to the deployments directory, you’ll see output like this generated by the WildFly server:

Make special note of this line of output:

This output indicates that the URL of the deployed example API is:

localhost:8080/apiman-echo

Remember, however, that this is the URL of the deployed example API if we access it directly. We’ll refer to this as the "unmanaged API" as we are able to connect to the API directly, without going through the API Gateway. The URL to access the API through the API Gateway ("the managed API") at runtime will be different.

Now that our example API is installed, it’s time to install and configure our client to access the server.

Accessing the Example API Through a Client

There are a lot of options available when it comes to what we can use for a client to access our API. We’ll keep the client simple so that we can keep our focus on apiman and simply use a browser as the client. If you enter the API’s URL into a browser, an HTTP GET command will be executed. The response will look like this:

Now that our example API is built, deployed and running, it’s time to create the organizations for the API provider and the API consumer. The differences between the requirements of the two organizations will be evident in their Apiman configuration properties.

OK, the preliminaries are over! Now, it’s time to go into the Apiman Management UI and create the Apiman data elements for our demonstration.

Creating Users for the API Provider and Consumer Organizations

Before we create the organizations, we have to create a user for each organization. We’ll start by creating the API provider user. To do this, logout from the admin account in the API Manager UI. The login dialog will then be displayed.

Select the "New user/Register" Option and register the API provider user:

Then, logout and repeat the process to register a new application developer user too:

Now that the new users are registered we can create the organizations.

Creating the API Provider Organization

To create the API provider organization, log back into the API Manager UI as the apiprov user and select “Create a new Organization”:

Select a name and description for the organization, and press “Create Organization”:

And, here’s our organization:

Note that in a production environment, users would request membership in an organization. The approval process for accepting new members into an organization would follow the organization’s workflow, but this would be handled outside of the API Manager API. For the purposes of our demonstration, we’ll keep things simple.

Configuring the API, its Policies, and Plans

To configure the API, we’ll first create a plan to contain the policies that we want applied by the API Gateway at runtime when requests to the API are made. To create a new plan, select the “Plans” tab. We’ll create a “gold” plan:

Once the plan is created, we will add policies to it:

Apiman provides several OOTB policies/plans. Since we want to be able to demonstrate a policy being applied, we’ll select a Rate Limiting Policy, and set its limit to a very low level. If our API receives more than 10 requests in a day/month, the policy should block all subsequent requests. So much for a “gold” level of API!

After we create the policy and add it to the plan, we have to lock the plan:

And, here is the finished, and locked plan:

At this point, additional plans can be defined for the API. We’ll also create a “silver” plan, that will offer a lower level of API (i.e., a request rate limit lower than 10 per day/month) than the gold plan. Since the process to create this silver plan is identical to that of the gold plan, we’ll skip the screenshots.

Now that the two plans are complete and locked, it’s time to define the API.

We’ll give the API an appropriate name, so that providers and consumers alike will be able to run a query in the API Manager to find it.

After the API is defined, we have to define its implementation. In the context of the API Manager, the API Endpoint is the API’s direct URL. Remember that the API Gateway will act as a proxy for the API, so it must know the API’s actual URL. In the case of our example API, the URL is: localhost:8080/apiman-echo

The plans tab shows which plans are available to be applied to the API:

Let’s make our API more secure by adding an authentication policy that will require users to login before they can access the API. Select the Policies tab, and then define a simple authentication policy. Remember the user name and password that you define here as we’ll need them later on when send requests to the API.

After the authentication policy is added, we can publish the API to the API Gateway:

And, here it is, the published API:

OK, that finishes the definition of the API provider organization and the publication of the API.

Next, we’ll switch over to the API consumer side and create the API consumer organization and register an application to connect to the managed API through the proxy of the API Gateway.

The API Consumer Organization

We’ll repeat the process that we used to create the application development organization. Log in to the API Manager UI as the “appdev” user and create the organization:

Unlike the process we used when we created the elements used by the API provider, the first step that we’ll take is to create a new application and then search for the API to be used by the application:

Searching for the API is easy, as we were careful to set the API name to something memorable:

Select the API name, and then specify the plan to be used. We’ll splurge and use the gold plan:

Next, select “create contract” for the plan (for this example, we’ll just accept all the defaults):

The last step is to register the application with the API Gateway so that the gateway can act as a proxy for the API:

Congratulations! All the steps necessary to both provide and consume the configure the API are complete!

There’s just one more step that we have to take in order for clients to be able access the API through the API Gateway.

Remember the URL that we used to access the unmanaged API directly? Well, forget it. In order to access the managed API through the API Gateway acting as a proxy for other API we have to obtain the managed API’s URL. In the API Manager UI, header over to the “APIs” tab for the application, select the API and then click select on the “i” character to the right of the API name. This will expose the API Key and the API’s HTTP endpoint in the API Gateway:

In order to be able to access the API through the API Gateway, we have to provide the API Key with each request. combine the API Key and HTTP endpoint. The API Key can be provided either through an HTTP Header (X-API-Key) or a URL query parameter.

In our example, the API request looks like this:

Copy the URL into the clipboard.

Accessing the Managed API Through the Apiman API Gateway, Watching the Policies at Runtime

Thanks for hanging in there! The set up is done. Now, we can fire up the client and watch the policies in action as they are applied at runtime by the API Gateway.

Open a new browser window or tab, and enter the URL for the managed API.

What happens first is that the authentication policy is applied and a login dialog is then displayed:

Enter the username and password (user1/password) that we defined when we created the authentication policy to access the API. The fact that you are seeing this dialog confirms that you are accessing the managed API and are not accessing the API directly.

When you send a GET request to the API, you should see a successful response:

So far so good. Now, send 10 more requests and you will see a response that looks like this as the gold plan rate limit is exceeded:

And there it is. Your gold plan has been exceeded. Maybe next time you’ll spend a little more and get the platinum plan 😅!

Let’s recap what we just accomplished in this demo:

And, if you note, in the process of doing all this, the only code that we had to write or build was for the client. We were able to fully configure the API, policies, plans, and the application in the API Manager UI.