Django SDK Guide

To integrate your Django application with APItoolkit, you need to use this SDK to monitor incoming traffic, aggregate the requests, and then send them to APItoolkit's servers. Kindly follow this guide to get started and learn about all the supported features of APItoolkit's Django SDK.

Prerequisites

Ensure you have already completed the first three steps of the onboarding guide.

Installation

Kindly run the command below to install the SDK:

pip install apitoolkit-django

Configuration

First, add the APITOOLKIT_KEY environment variable to your .env file, like so:

APITOOLKIT_KEY={ENTER_YOUR_API_KEY_HERE}

Next, add the APITOOLKIT_KEY to your Django settings (settings.py) file, like so:

from pathlib import Path
from dotenv import load_dotenv
import os

load_dotenv()

# Build paths inside the project like this: BASE_DIR / 'subdir'.
BASE_DIR = Path(__file__).resolve().parent.parent

# Add the APItoolkit configuration options
APITOOLKIT_KEY = os.getenv('APITOOLKIT_KEY')
APITOOLKIT_DEBUG = False
APITOOLKIT_TAGS = ["environment: production", "region: us-east-1"]
APITOOLKIT_SERVICE_VERSION = "v2.0"

# Application definition
INSTALLED_APPS = [
  'django.contrib.admin',
  'django.contrib.auth',
  'django.contrib.sessions',
]

Then add the apitoolkit_django.APIToolkit middleware into the settings.py middleware list, like so:

MIDDLEWARE = [
  'apitoolkit_django.APIToolkit',  # Initialize APItoolkit
  'django.middleware.security.SecurityMiddleware',
  'django.contrib.sessions.middleware.SessionMiddleware',
  'django.middleware.common.CommonMiddleware',
  # Add other middleware as needed
]

In the configuration above, only the APITOOLKIT_KEY option is required, but you can add the following optional fields:

Redacting Sensitive Data

If you have fields that are sensitive and should not be sent to APItoolkit servers, you can mark those fields to be redacted (the fields will never leave your servers).

To mark a field for redacting via this SDK, you need to add some additional configuration options to the settings.py file with paths to the fields that should be redacted. There are three variables you can provide to configure what gets redacted, namely:

1. APITOOLKIT_REDACT_HEADERS: A list of HTTP header keys.
2. APITOOLKIT_REDACT_REQ_BODY: A list of JSONPaths from the request body.
3. APITOOLKIT_REDACT_RES_BODY: A list of JSONPaths from the response body.

{
  "user": {
    "name": "John Martha",
    "email": "[email protected]",
    "addresses": [
      {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      },
      {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      }
    ],
    "credit_card": {
      "number": "4111111111111111",
      "expiration": "12/28",
      "cvv": "123"
    }
  }
}

Examples of valid JSONPath expressions would be:

Here's an example of what the settings.py file would look like with redacted fields:

APITOOLKIT_REDACT_HEADERS = ["content-type", "Authorization", "HOST"]
APITOOLKIT_REDACT_REQ_BODY = ["$.user.email", "$.user.addresses"]
APITOOLKIT_REDACT_RES_BODY = ["$.users[*].email", "$.users[*].credit_card"]

Error Reporting

APItoolkit automatically detects different unhandled errors, API issues, and anomalies but you can report and track specific errors at different parts of your application. This will help you associate more detail and context from your backend with any failing customer request.

To manually report specific errors at different parts of your application, use the report_error() function from the apitoolkit_django module, passing in the request and error, like so:

from django.http import JsonResponse
from apitoolkit_django import observe_request, report_error

def hello_world(request, name):
  try:
    value = 1/0
    return JsonResponse({"hello": value})
  except Exception as e:
    report_error(request, e)
    return JsonResponse({"Error": "Something went wrong..."})

Monitoring Outgoing Requests

Outgoing requests are external API calls you make from your API. By default, APItoolkit monitors all requests users make from your application and they will all appear in the API Log Explorer page. However, you can separate outgoing requests from others and explore them in the Outgoing Integrations page, alongside the incoming request that triggered them.

To monitor outgoing HTTP requests from your application, use the observe_request() function from the apitoolkit_django module, passing in the request argument, like so:

from django.http import JsonResponse
from apitoolkit_django import observe_request, report_error

def hello_world(request, name):
  resp = observe_request(request).get(
      "https://jsonplaceholder.typicode.com/todos/2")
  resp.read()
  return JsonResponse({"data": resp.read()})

The observe_request() function accepts a required request argument, and the following optional arguments: