Setting up your apiman development environment

Note: This is a redux of our blogpost for apiman 1.2.x. If you're still using apiman 1.1.x, you can refer to the older revision.

For those of you who might be interested in hacking away at some core apiman code,
I thought it might be nice to create a reasonably comprehensive step-by-step
guide. For the most part everything is straightforward, but there are a copule
of tricks you can use to get up and running fast and to be able to easily
iterate on any changes you make.

Read on if this sounds like something you want to do!

What will this post cover?

Here is a high level overview of the steps we’ll take to getting a working
apiman development environment. First, here are my basic assumptions:

You are a java developer and have JDK7 or higher installed

You are familiar with maven and have it installed

You know git and have it installed

You want to use the Eclipse IDE

Assuming you meet all of the above requirements, you should have no trouble
with this guide! Here is what this post will cover:

Getting the apiman source code

Downloading and running Eclipse

Configuring Eclipse for apiman development

Importing the apiman source code into Eclipse

Running Development versions of the apiman components

Getting the apiman source code

The first thing you (obviously) need to do is download the apiman project
source code. All of the code is in github, of course. You can find the
code here:

The ‘apiman’ github organization has a couple of additional repositories as
well. For example the quickstarts and plugins each have their own repos.
But let’s stick with the core code for this post.

If you want to follow best practice, you should “fork” the apiman repository
on github, then clone your forked copy. Once you have used the github UI
to fork the repository, you would do something like this:

git clone git@github.com:<YOUR-GITHUB-ID>/apiman.git

I also recommend adding the upstream github repository as another remote
so that you can easily pull in upstream changes:

git remote add upstream git@github.com:apiman/apiman.git

Downloading and running Eclipse

Alright - you’ve got the apiman code cloned on your local hard drive
somewhere. The next step is to download Eclipse (if you don’t already
have it installed). This can be done here:

I like to download the “Eclipse IDE for Java EE Developers” version
because it comes with a lot of extra stuff I like to use. But you should
be fine with the basic version as well. I’m going to use the EE version
as I write this guide!

Once you’ve completed the download, just unpack it and run Eclipse.

Configuring Eclipse for apiman development

Great! You’ve got Eclipse running. Now let’s make a minor change
to it specific to apiman development. Go ahead and import the apiman code
formatter specification. You can find this file in the apiman code
repository here:

apiman/tools/src/eclipse/apiman-eclipse-formatter.xml

Import that file in the Eclipse Preferences dialog here:

Importing the apiman source code into Eclipse

OK now we’re ready to import the apiman source code into Eclipse. Because
apiman uses maven as its build system, and because Eclipse has maven support
built-in via m2e, this should be a snap. Simply go to File->Import and
choose Maven/Existing Maven Projects:

Importing the projects into Eclipse may take some time, and Eclipse may
yell at you about unresolved m2e plugins and whatnot. Make sensible choices
(e.g. resolve later) and go about your life. Go get a cup of coffee, the
build will probably take a few minutes.

It is possible you will run into a problem where the apiman-manager-ui-hawtio
project gets into a build loop. This can be corrected by disabling the
maven builder for that one project only. Do this by right-click on that
project and choosing properties:

Typically this will leave you with a bunch of annoying warnings in Eclipse,
most of which will be HTML Problems. I will leave it as an exercise to the
reader about how to disable those.

IMPORTANT: you should have 0 java errors at this point!

Running Development versions of the apiman components

Everything should now be loaded into Eclipse. Now all you need is a quick
way to run everything. Of course you can always do a full rebuild via
maven and use the “install-all-wildfly8” profile:

cd ~/git/apiman
mvn clean install -Pinstall-all-wildfly8

That will result in a full apiman environment installed in WildFly 8. If you
use this approach you can run apiman here:

Now whenever you make changes to any of the apiman angularjs code, the browser
will automatically refresh and show you the changes!

Launching a dev version of the API Gateway

This one is easy as well. Just open up the GatewayDevServer java class
and debug it as an application (just like the API Manager above!)…

Wrapup

Whew! That took longer than I thought. Please let me know if you run into
any snags. There are probably lots of improvements you could explore, such as
using JRebel to never have to restart the API Manager or API Gateway java
processes again.