Getting Gravitee.io API Management platform up and running on a local machine

If you’re new to Gravitee.io, you may want to have a go at having some hands-on experience working with the product. In this blog post we’ll show you how to quickly and easily get the Gravitee.io API Management (APIM) platform up and running on your local machine using Docker, as well as deploying your first API.

Setting up APIM

In this post we’re going to do a step-by-step process of getting API Management up and running on your local machine, using the available Docker Compose file from the download page. From there, we’re going to get up and running our very first API, based on the Swagger Petstore example. As always, if you’ve got any questions, do reach out on our community forum.

If you’ve not already done so, you’ll want to install Docker. I’m on a Windows machine, so I’ll be using Windows Subsystem for Linux (WSL) to start the Gravitee Docker container.

Once you’re all set up, we’re now going to download the Gravitee.io APIM Docker Compose file. Firstly, make sure you’ve got a command prompt up and running (e.g. on your Linux/Mac machine, or WSL on windows). Next, we’re going to download it using curl, so firstly navigate to your chosen directory, and then run the following command:

curl https://raw.githubusercontent.com/gravitee-io/gravitee-docker/master/apim/3.x/docker-compose.yml -o docker-compose.yml

If you get an error, you may not have write rights in your chosen directory — make changes as is necessary.

Once downloaded, we’re now going to use the docker compose file to download and start running all of the components required for APIM. We can do this by running the following command:

docker-compose up

Depending on your internet connection, this may take a while as all of the relevant components are downloaded and installed onto your machine. Keep an eye on the console until you start seeing logging messages gateways/consoles being up.

That’s it! We’re now up and running. Let’s now look at the next part of this post where we deploy an API into the Gravitee.io API Gateway.

Deploying your first API

We are firstly going to go to the APIM Management console to be able to create and deploy our first API. To access the console, go to the following address: http://localhost:8084

The default credentials are:

• Username: admin
• Password: admin

Once logged in, you’ll be greeted with the console dashboard. In a future post we’ll go into more detail about the console, but for now, let’s get that first API up and running!

Firstly, click on ‘APIs’. This will bring up the list of existing APIs as well as the option to create a new one. As we’re creating a new one, click on (+):

The Design Studio pane will appear. There are two options available to us:

• Import allows us generate API settings based on an existing API specification
• Create allows us to create the API settings from scratch

We are going to use an existing API specification. For this example, we’ll use the Swagger PetStore API example. Download a copy, and click ‘Import’ and then ‘Choose File’ on the next screen:

Once the file has been selected, you will have some additional options available to you. Again, in an upcoming blog post we’ll go into more detail, but for now, ensure that you have the circled options also selected:

• ‘Create policies on path’ — this option will create each endpoint and associated methods based on the imported swagger file
• ‘Apply Mock policies’ — this option will create a mock policy for each endpoint based on examples provided in the imported swagger file

Then click import:

A screen with options to configure your API will now appear. Don’t worry about the gold bar ‘API out of sync, deploy your API’, we have a number of things to do first.

To be able to test out our API, we will need to create a plan. A plan always needs to be created, and gives us the ability to control how an API is accessed. For this example, we’re going to create a keyless plan — this will allow anybody to access the API. Select ‘Plans’, the Plans window will appear:

To add a new plan, press (+). Then provide a Name and Description for the plan, scroll down and click ‘Next’:

On the next screen, select ‘Keyless (public)’ from the ‘Authentication type’ drop-down menu:

Keep clicking through on ‘Next’ until you’ve completed the plan creation process. We will now need to publish the plan so that it can be used. Click the picture of the Cloud with the upward pointing arrow:

The last step that remains is to start the API. Go to ‘Details’ under ‘General’, scrolling down to the ‘Danger Zone’. Select ‘START THE API’. This will sync the deployment of the API and associated plan, as well as starting the API itself.

Go to Gateway

Now that we’ve deployed the API, let’s go and test it out on the Gravitee.io APIM Gateway.

The Gateway address is accessible from port 8082. We’re going to now call one of the endpoints from the Swagger Petstore which will bring back mock data using the automatically created policy when we imported the Swagger file:

http://localhost:8082/v2/pet/petid

Success! If you like, why not have a go at calling some of the other endpoints listed in the Swagger Petstore file, or alternatively, try importing another API definition file and follow the process above.

Wrapping up

In this blog post we did a walk through of how to get the Gravitee APIM platform up and running using the available Docker Compose file. In addition, we also saw how we could get an API up and running, as well as testing it out. We’d love to know how you get on! If you’ve got any questions, do reach out on our community forum.