APIs & Integration

FDEs spend much of their time connecting a product to a customer's systems. That means talking to APIs over HTTP, authenticating securely, reacting to events as they happen, and using SDKs instead of reinventing wheels. This tutorial covers the whole integration toolkit.

What Is an API?
HTTP and REST
JSON Data
A Full Request Example
Why Authentication Matters
API Keys and Tokens
Environment Variables
A Safe API Call
Webhooks
SDKs and Libraries

What Is an API?

An API (Application Programming Interface) is a contract that lets one program ask another for data or actions. Instead of clicking buttons, your code sends a request and gets a structured response.

Why useful: FDEs use APIs to pull customer data, push results, and wire the product into existing workflows.

HTTP and REST

HTTP is the protocol of the web; REST is a style of API built on HTTP verbs. The common verbs:

GET — read data
POST — create data
PUT/PATCH — update data
DELETE — remove data

GET /tickets/101 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_KEY

Explanation: this GET asks for ticket 101. REST maps resources (like tickets) to URLs and uses HTTP verbs for the action. Most FDE integrations are REST over HTTPS.

Note: Always use HTTPS (the secure version) when handling customer data.

JSON Data

JSON (JavaScript Object Notation) is the text format APIs use to send data. It looks like nested key-value pairs and lists.

{
  "id": "101",
  "subject": "Login fails",
  "active": true,
  "tags": ["auth", "urgent"]
}

Explanation: keys are strings (in quotes), values can be text, numbers, booleans, arrays (tags), or nested objects. Both Python and JS parse JSON into native structures directly.

Best Practice: Validate the JSON shape you receive — customer APIs often return missing or extra fields.

A Full Request Example

Here's a complete REST call using curl, then the JSON you'd get back:

curl -H "Authorization: Bearer YOUR_KEY" \
     https://api.example.com/tickets/101

{ "id": "101", "subject": "Login fails", "active": true }

Explanation: curl is a command-line tool for sending HTTP requests — handy for quickly testing a customer's API before writing code. The response is JSON you can inspect.

Common Mistake: Assuming every endpoint returns the same fields. Check the actual response, especially with legacy customer systems.

Why Authentication Matters

Authentication proves who is calling the API. Without it, anyone could read a customer's data or run up their bill. FDEs handle customer credentials constantly, so getting this right is non-negotiable.

Why useful: Secure auth builds customer trust and keeps you compliant.

API Keys and Tokens

An API key is a long secret string identifying your app. A token (often a JWT or "Bearer" token) represents a logged-in session.

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "X-API-Key": "abc123..."
}

Explanation: the Authorization: Bearer header sends a token; some APIs also want a key header. The server checks these before responding.

Common Mistake: Putting the key directly in source code that gets committed to Git — now the secret is public.

Best Practice: Treat keys like passwords; rotate them if exposed.

Environment Variables

An environment variable is a value stored outside your code, in the system or a .env file. Your program reads it at runtime.

import os
API_KEY = os.getenv("API_KEY")  # read from environment

# .env file (never commit this)
API_KEY=abc123...

Explanation: os.getenv("API_KEY") pulls the secret from the environment instead of hard-coding it. The .env file holds the value and is kept out of version control.

Best Practice: Add .env to .gitignore so secrets never reach the repo.

Note: Environment variables are the standard way FDEs inject config (keys, URLs, regions) per customer without changing code.

A Safe API Call

import os, requests

API_KEY = os.getenv("API_KEY")
resp = requests.get(
    "https://api.example.com/tickets",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
print(resp.status_code)

Explanation: the key comes from the environment, never the file. If the call fails, status_code tells you why (401 = unauthorized, 404 = not found, 200 = OK).

Common Mistake: Ignoring status_code and assuming success — always handle non-200 responses.

Webhooks

A webhook is an HTTP callback — a URL you expose that a service hits when an event occurs (a new ticket, a payment, a deploy). Instead of you polling, the event comes to you.

Why useful: FDEs use webhooks to trigger actions the moment customer data changes, without constant polling.

How a webhook flows:

You register a URL (endpoint) with the source service.
An event happens (e.g., new support ticket created).
The service sends an HTTP POST with event data (JSON) to your URL.
Your code processes it and responds 200 OK.

Note: Your endpoint must be publicly reachable (or tunneled via a tool like ngrok during local testing).

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def handle():
    event = request.get_json()
    print("New event:", event["type"])
    return "", 200

Explanation: a tiny Flask server listens at /webhook. When the source POSTs JSON, request.get_json() parses it and we log the event type, then return 200 to confirm receipt.

Best Practice: Respond quickly (200) and do heavy work asynchronously, so the sender doesn't time out.

Security: Services often sign webhooks; verify the signature before trusting the body.

signature = request.headers.get("X-Signature")
if not verify(signature, request.data):   # verify() is the provider's helper
    return "invalid", 401

Common Mistakes:

Not verifying signatures — anyone could fake events.
Doing slow work in the request, causing retries and duplicates.
Forgetting to return 200, so the sender retries repeatedly.

SDKs and Libraries

A library is a reusable package of code (e.g., requests for HTTP). An SDK is a library (or set) officially provided by a service to use its API correctly and easily.

Why useful: Both save FDEs from reimplementing common logic — critical when integrating many customer systems quickly.

Note: An SDK usually wraps an API you could call manually; it just handles auth, retries, and data shapes for you.

pip install openai      # Python
npm install @sendgrid/mail  # Node

from openai import OpenAI
client = OpenAI()   # reads API key from environment

Explanation: package managers (pip, npm) install the code; import brings it into your script. Good SDKs read config like API keys from the environment automatically.

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Summarize this ticket"}]
)
print(response.choices[0].message.content)

Explanation: instead of hand-crafting HTTP requests, the SDK's create method sends the call with proper auth and returns a typed object. Far less code, fewer bugs.

Best Practices:

Prefer the official SDK over raw HTTP when one exists — it handles edge cases you'd otherwise miss.
Pin versions (requests==2.31.0) so a customer's setup doesn't break on updates.
Read the SDK's docs for rate limits and retries.
Common Mistake: Installing untrusted packages. Stick to official or well-maintained libraries for customer data.
Note: An SDK is still just code — review what permissions it requests before deploying.

APIs and External Integrations for FDEs: HTTP, REST, Auth, Webhooks & SDKs

Table of Contents