Api Watch Tower

A simple but effective open-source tool to control and monitor your APIs

7 min readJan 17, 2021

This simple Grafana dashboard is created using the live data provided by AWT

Working with APIs is an integral part of the daily work of Software Engineers and Software Developers. Collaboration between software developer teams and API providers is crucial for creating new features. However, there are often instances of miscommunication or changes to initial agreements between these teams. Have you ever experienced a situation where calls to an API suddenly stopped working or the response format changed, causing numerous problems? Sometimes API failures occur for a short period of time, and you discover the exceptions in your application later on. This requires investing time, sometimes a significant amount, to investigate these errors by analyzing the logging levels, only to find out that there is an issue with the API provider. If you’ve faced these challenges, you’re not alone, and that’s where AWT comes in to assist you.

While there are tools like Postman available to test APIs, there is a need for periodic and automated checks that can be set up on a server accessible to your team. However, I couldn’t find any existing watchdog tools that met my requirements. That’s why I created ApiWatchTower, an open-source tool designed to not only perform health checks on APIs based on their response codes but also validate the expected response body. AWT functions as an API call scheduler, enabling periodic health checks and the execution of batch processes to determine whether an API is functioning properly. AWT also supports chained calls, which are useful when you need to call multiple APIs in a specific order, such as retrieving an authentication token from one call to use in a subsequent call. In the following sections, we will learn how to set up and utilize this tool effectively.

If you need a fast review of the application you may use the demo version but have in mind that this demo version does not have all the features, is not efficient and secure, is not going to be updated, and is not meant to be used instead of the official tool itself.

Installation

You can build it from source code but The easiest way to setup is using the public docker container abo0zar/api_watch_tower:latest using the following Yaml file:

# docker-compose.yml

version: '3'

services:
  postgres:
    image: postgres
    restart: always
    environment:
      - POSTGRES_DB=AWT
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    volumes:
      - postgresData:/var/lib/postgresql/data
    expose:
      - "5432"

  redis:
    image: redis
    restart: always
    command: redis-server
    expose:
      - "6379"

  awt_admin:
    image: abo0zar/api_watch_tower:latest
    restart: always
    command: bash -c 'python manage.py migrate auth && python manage.py migrate && python manage.py runserver 0.0.0.0:8000'
    ports:
      - "8000:8000"
    depends_on:
      - postgres
    environment:
      - AWT_LANGUAGE_CODE=en
      - AAD_TENANT_ID=xxxOptionalxxx
      - AAD_CLIENT_ID=xxxOptionalxxx
      - HTTPS=off

  awt_worker:
    image: abo0zar/api_watch_tower:latest
    command: celery -A ApiWatchTower worker -B --concurrency=10
    depends_on:
      - redis
      - postgres
      - awt_admin

  awt_scheduler:
    image: abo0zar/api_watch_tower:latest
    restart: always
    command: celery -A ApiWatchTower beat -l info -S django --pidfile=
    depends_on:
      - redis
      - postgres
      - awt_admin
      - awt_worker

  grafana:
    image: grafana/grafana:latest
    restart: always
    container_name: "awt_grafana"
    volumes:
      - grafanaStorage:/var/lib/grafana
    depends_on:
      - postgres
    ports:
      - "3000:3000"
    environment:
      - GF_INSTALL_PLUGINS=snuids-trafficlights-panelvolumes:
    postgresData:
    grafanaStorage:

Just save the code in a file named “docker-compose.yml” and run:

docker-compose up

now open http://localhost:8000 to access to your AWT Admin and login with the default username and password: “admin”

Also you can configure the Microsoft AD to login by setting the right “AD Tenant Id” and “AD Client Id” in your docker compose file.

For accessing to your Grafana open your browser and go to http://localhost:3000 and login with the default username and password: “admin”.

For production environment use Nginx and configure a reverse proxy for Grafana to access AWT admin and Grafana on the same domain at port 80. For example you can set your AWT admin at https://my-domain-name.com/admin and your Grafana at https://my-domain-name.com/monitor.

Initialize

Open the web browser and go to the admin page and login. In the left menu under “Periodic Tasks” click on “Periodic Tasks” again. Here you should add your main scheduler to call all to API rules that you are going to create in the next steps. click on “+ Add periodic task” on the top right.

Choose a name and from the “Task (Registered)” drop down menu select “HealthChecker.tasks.check_health” that is the main task to check all the saved rules and run them.

Choose Name and select “HealthChecker.tasks.check_health”

Now go to the “SCHEDULE” tab and create a new one, for example an interval schedule every 10 seconds. Then click on “Save”.

Great! now that you’ve set your main periodic task we can create our first AWT Health Check Rule!
Under “HealthChecker” in the right menu click on “Health Check Rules”.

Now click on “+ Add health check rule”. Set the Name of your rule, then fill the “URL” for example “https://www.google.com” and click on “Save”.

Now to see the results just go to “Health check records” and there you go! every 10 seconds you’ll see a new record is adding there.

If you click on one of the records id you can see a more complete result, in the Request field you’ll see the CURL form of your Http call, you’ll see also the Response code, Response Body, Call Delay, Success (the complete explanation in the following) and also Timestamp.

Success is the comparison of Expected Response code and Expected Response Body with the real ones

Health Check Rules Parameters

Name: Health check rule name
Url: http or https URL
Http method: Currently AWT supports GET and POST Calls
Headers: Create Http Headers by clicking on the “+” or reuse the existing
Request body: In case of Post you can pass your request body here
Client certificate: create a new client by clicking on the “+” and uploading your Certificate.pem and Key.pem. After uploading they are not Readable/Downloadable for the security reasons.

Expected response code: Usually 200, it is considered to calculate the “Success” parameter in the Health check records.

Expected response body: It’s a simple string or a regular expression to be searched in the response body. It is considered to calculate the “Success” parameter in the Health check records.

*Success is the boolean result of [Expected Response code == Real Response code && Response Body MATCH Expected Response Body]

Enable: To Activate or Deactivate the rule.

Output variables: To extract variables from a JSON response and save it in an environment variable. For example imagine the following JSON response from an API is like the following:

{
   "code": 189436,
   "description": "SUCCESS",
   "result": {"token": "45t4ethyJhbGciO45y"}
}

Here we can save the values of “code” and “token” in two new environment variables named “A” and “B” by setting the Output variables like this:

code=>A, result__token=>B

“=>” is used to assign
“__” is used to select inner key, can be more than one
“,” is used to separate assignments if more than one
“ ” space will be ignored

Run after: If selected, the current rule should be executed after the selected rule, it’s useful for chained rules where you should use the output of one rule for the input of the next rule. In that case use the “output variables” explained previously to fill your environment variables and the use them, with the same names like this: {{variable_name}}
So for the previous example we will have:

{{A}}
{{B}}

Environment variables having this format can be used in the Header, URL and Request Body.

Grafana

Having all the data that is needed periodically saved into the “Health check records” table, it’s easy to use them to visualize the real-time data in Grafana.

After logging in to your Grafana, connect the postgres database to your Grafana dashboard.

Configuration > Add Data Source > PostgreSQL

And set all the configurations that you already passed to your docker container, if default, the database should be “AWT” and host, username and Pass should be “postgres”, disable the SSL mode, select the suitable version of postgreSQL (default is the latest) and Click on “Save and Test”.

Now you can create your own dashboards but to give you an example you can start with a simple demo dashboard. Click on the “+” on the left menu and click on import. Copy this sample to “Import via panel json” and click on Load.

You can change the queries and create your own panels to visualize the data.

If you have any more questions, please do not hesitate to ask.