A Wizard’s Pocket Guide to APIs in Gravity Forms

1. What you need to get started with API Alchemist
   1. Mapping responses
   2. Configuring requests
   3. The weeds of API docs
      1. What to look for in API docs:
   4. Good luck out there
2. What is an API, really?
3. Understanding REST APIs
   1. What is REST?
   2. What is HTTP?
      1. HTTP Requests
      2. HTTP Responses
      3. Web of Webhooks
4. Data Format
   1. Common Data Formats in APIs
   2. Why is JSON so popular?
      1. JSON Basics
5. API Specifications
   1. Common Specification Formats
   2. API Schema
6. Bubble, bubble, toil and trouble!

APIs connect the web, but what are they, and how do they work, really? This beginner-friendly guide to APIs in Gravity Forms answers those questions in just enough detail to help you hit the ground running.

I’m going to use our product, API Alchemist, as a base to show you the way. But most of this information applies to whichever product you use!

What is API Alchemist?

API Alchemist connects Gravity Forms to pretty much any external service via APIs, allowing you to:

• Send form data to that service, connecting your forms to the rest of your workflow, and
• Pull data from that service to be used live in form fields, confirmations/notifications, other services, you name it.

Its no-code UI is very smart (like, auto-mapping smart), making working with APIs in Gravity Forms a breeze once you understand the basics.

What you need to get started with API Alchemist

(Skip the crash course.)

If I were to give you a 3-minute crash course that allows you to jump straight into API Alchemist, here’s what I would say:

APIs allow you to interact with services — either external ones or your own site.

Depending on the available endpoints the API provides, you’ll be able to get, add new, update, or delete certain information remotely via form submission. Cheatsheet:

• GET: Lets you get information.
• POST: Lets you add brand new information.
• PUT / PATCH: Lets you edit existing information (which you can add to or delete). PUT is more common.
• DELETE: Lets you delete information.

That information moves back and forth as requests and responses. With API Alchemist, you can:

• Set up requests through feeds
• Map response data in two scenarios:
  • Response handling, which lets you capture API data after submission
  • Populate Anything Endpoints, which brings API data live into your forms.

Mapping responses

When mapping responses, you’ll see an interactive tree showing a real sample response from the API you’re mapping from. The tree makes JSON (a data format) even more human-friendly than it already is. You’ll be able to drag and drop JSON properties to form fields or Populate Anything objects.

Even not being familiar with JSON, this step felt super intuitive to me. If you have any questions, let me know in the comments below so I can update the guide!

Configuring requests

When configuring your requests, you’ll see:

• (URL) query parameters for GET and DELETE requests. These narrow down where in an endpoint your request goes to.
• Headers, which are mostly used to include authentication, data format, and caching details. All those things are taken care of by API Alchemist in other places of the UI — for most APIs, you won’t need to use the “Headers” section of API Alchemist feeds.
• Body (aka payload) for POST, PUT, and PATCH requests. This is where the information lives, most often formatted in JSON. API Alchemist takes care of the formatting behind the UI too.

The weeds of API docs

The next step varies from API to API. What is the information you’re interacting with? What are the words the API builders chose to refer to each thing? Those answers live in the API’s documentation.

Being real here, some docs are clearer than others. You’re already halfway to understanding them by knowing these basic API principles and what you’re planning to do with the API. They will get easier to navigate over time.

What to look for in API docs:

1. The base URL for the API (e.g. https://carapi.app/, http://api.openweathermap.org/).

2. If it requires any authentication. Some authentication types like keys and tokens can be done directly through the feed using headers or query parameters, but I suggest setting up an API Connection Profile for ease of use.

3. If it has a schema available. A quick way to do so is to paste the base URL into an API Connection Profile and save. This triggers the schema auto-detect, which looks for schemas at common endpoints. API Alchemist uses schemas to import endpoints, query and JSON properties to bake them into the UI so you don’t have to reference the API docs all the time.

   If API Alchemist doesn’t find anything, you can still try to see if it’s hidden somewhere — I’d say the level of simplicity it provides makes it worth the effort.

4. If a schema isn’t available, look for a list of available endpoints, they will guide you on what you can do with that API. Once you decide which endpoint you want to interact with, you’ll likely see the query parameters or JSON keys right there. You’ll use them when mapping your requests.

Good luck out there

That’s the end of the super-condensed crash course. As you can see from the long table of contents, this guide explores a little deeper into what is going on to give you a more solid understanding of APIs.

But, if you want to jump right into the API waters, API Alchemist and its docs have your back and won’t let you drown now that you know these very, very basics.

If you’d like to stay dry with me a while longer, let’s answer some burning questions I certainly had when I dipped my toes in APIs for the first time. Starting with…

What is an API, really?

An Application Programming Interface (API) is a web service for providing an interface of communication between two systems — a bridge.

Both systems can have an API, or like in the case of API Alchemist, one of the systems has an API and the other has a tool (or alchemist 😉) that interacts with that API. A single API is enough for interaction to happen.

One system acts as the client, initiating an action, asking for information, or sending a message. The other system acts as the server, which performs the action, provides the information, or receives the message. These roles are interchangeable between systems — one system can be the client for one interaction, but the server for another.

Most APIs have:

• A type of architectural style.
• A protocol that defines how the two systems communicate.
• A data format for exchanging information.
• A specification, which works like a grammar book defining the API’s rules, endpoints, and data contracts.

For example, imagine a certain API communicates via chat instead of email (type). The chat requires each message to start with the sender’s name and timestamp (protocol), the message itself is in plain text instead of images (data format), and the chatrooms (endpoints) you interact in plus the language that is used—its rules, words, and grammar—make up the specification.

APIs are widely used in the web and beyond. I was surprised to learn they’re actually the standard for system-to-system communication. There are countless types, protocols, data formats, and specifications — then there are countless combinations between them. If we were to cover them all, we’d be here all week, our potions would go sour, and our heads, bald. So…

Understanding REST APIs

The most prevalent combination of API type and protocol on the web are REST APIs (type) using HTTP (protocol). 

What is REST?

To understand REST, let’s focus on what the systems are doing within that framework.

One system sends a snapshot of one or more resources (e.g., users, products, posts) that can be used to display the snapshot itself or to modify the original resource based on that snapshot. 

Think of it like taking a picture of yourself. That picture isn’t you, it’s a representation of your state at that moment (what your hair looks like, what you’re wearing, etc.). You can edit your hair color in the picture, but your real hair doesn’t change unless you use that edited picture to send instructions back to the “real world” — to the original resource, which is you.

Similarly, in REST APIs, you can modify the state of a representation, but the state of the original resource only changes when you send the updated representation back via an API request.

What is HTTP?

HTTP (HyperText Transfer Protocol) is a universally supported system-level protocol that defines:

• How messages are formatted and transmitted between systems, and
• How servers and clients should respond to those messages.

That can sound complicated, but it follows a simple request/response structure. A client sends a request and the server comes back with a response. Boom.

HTTP Requests

There are a few types of HTTP requests, referred to as methods. Each method uses a verb that defines what the client wants from the server.

Here are the ones you need to know:

• GET: The client wants to read information about a resource, so it asks the server to retrieve it. Sometimes, a GET is used simply to trigger server-side behavior or to confirm the endpoint is reachable without needing to use the response.
• POST: The client wants to create a new resource, so it asks the server to add it.
• PUT: The client wants to replace an entire resource with new information, so it asks the server to update it completely.
• PATCH: The client wants to update part of a resource, so it asks the server to apply the changes.
• DELETE: The client wants to erase a resource, so it asks the server to delete it.

Each request usually has two main parts:

• Headers: Extra details the client sends along with the request, like authentication tokens, content type (JSON, form data, etc.), or instructions for caching. Headers give the server context about how to handle your request.
• Body: The main content of the request. Not all requests have one—GET requests often don’t—but when creating or updating resources (like with POST, PUT, or PATCH), this is where the data lives.

Requests are also independent. The server doesn’t automatically remember prior interactions unless extra mechanisms (like cookies, sessions, or tokens) are added.

HTTP Responses

Once a server gets a request, it replies with an HTTP response, which must include:

• A status code: A three-digit number that tells the client if the request succeeded, failed, or needs further action. The most common status codes are 200 (OK), 404 (Not Found), and 500 (Internal Server Error).
• Data (Body): The actual content the server is sending back. This could be HTML (for web pages), JSON or XML (for APIs), or even a file (like an image or PDF).

Responses usually also include other headers, which provide extra details such as the type of content (Content-Type: application/json), caching rules, or authentication info.

Web of Webhooks

Webhooks were very confusing to me starting out. Now that I understand them, it’s simple.

A webhook is a pattern: “when something happens, send an HTTP request to a URL I gave you.” In other words, a way for one system to automatically send data to another when an event occurs.

Webhooks are widely used as an alternative to polling. Instead of repeatedly checking if something happened (polling), a system notifies the other only when something does happen. In the case of API Alchemist, that “something” is a form submission.

What was confusing to me is that the word “webhook” can refer to different aspects of this pattern — the mechanism, the request, or a special URL that receives webhooks. Let’s untangle this web:

• The mechanism: One system automatically pushes data to another when an event happens.
• The request itself: The actual HTTP request carrying the event data.
• The webhook URL: A special endpoint designed specifically to receive webhook requests.

As an example, here’s how these aspects appear in API Alchemist:

• Webhook mechanism: All requests use a webhook mechanism to automatically push form data to an API endpoint after submission. Unlike a manually programmed API request, this is push-based and event-driven.
• Webhook request: The HTTP request itself contains the form data being sent to the API endpoint.
• Webhook URL: In Advanced Response Handling, API Alchemist creates a callback URL (i.e webhook URL) to include in the outgoing request. The external API can then push data back automatically via its own webhook request.

By breaking webhooks down this way, it’s easier to see how the pattern works and how the same term can describe different things depending on context.

Data Format

Now that we’ve seen how data moves between systems via HTTP requests and responses, let’s peek inside the package itself. How is this information structured? That’s where data formats come in. 

Computers can only understand information in very specific ways, they need a structure that the data must follow so both sides understand it correctly.

Common Data Formats in APIs

• JSON (JavaScript Object Notation): The most popular today.
• XML (eXtensible Markup Language): Older, more verbose.
• Form data: Simpler, often used in web forms.
• Raw data: No specified format. Not common, but possible.

Why is JSON so popular?

JSON is a clean, lightweight way to organize data that can be understood by computers and humans alike. Check out this example:

{
  "user": {
    "id": 777,
    "name": "Harry",
    "email": "harry@hogwarts.com",
    "houseColors" : ["red", "gold"],
    "status": "active"
  }
}

Pretty straightforward, right?

JSON Basics

API Alchemist deals with most of the JSON formatting for you, but if you find yourself needing to edit it, here are the 10 things you need to know:

1. Data roots are in key/value pairs

   • Written as "key": value or "key": "string"
   • Example: "name": "Harry"

2. Keys must be strings

   • Always in double quotes (” “)
   • They are case sensitive ("Name" ≠ "name")
   • Example: "id": 777

3. Values can be:

   • A string → "hello"
   • A number → 123 or 3.14
   • A boolean → true or false
   • Null → null
   • An object → { "nested": "data" }
   • An array → [1, 2, 3]

4. Objects are enclosed in { }

   Example:

   {
     "id": 1,
     "status": "active"
   }

5. Arrays are enclosed in [ ]

   Example:

6. {
     "colors": ["red", "gold", "green"]
   }

7. Nested structures are supported

   • Objects can contain other objects or arrays
   • Arrays can contain objects, arrays, or simple values

   {
     "user": {
       "id": 777,
       "name": "Harry",
       "house": {
         "name": "Gryffindor",
         "colors": ["red", "gold"]
       }
     }
   }

   Here, "user" contains another object ("house"), and "house" contains an array ("colors").

8. Commas separate items

   • Objects: between key/value pairs
   • Arrays: between values, no trailing commas

9. Comments aren’t allowed

10. Whitespace is ignored

    Indent however you like — formatting is just for humans.

API Specifications

The final frontier, API specifications (aka API docs).

They are the formal document (or set of documents) unique to each API that describes exactly what it provides and how it works. Here’s what you can find in a specification:

• What endpoints exist (URLs or paths like /weather/today).
• Which HTTP methods are allowed.
• What data must be included in a request.
• What data must be included in a response.
• Rules for authentication/authorization, if needed.

Imagine them as an instruction manual that both API providers and consumers follow for clarity and consistency. This practice also facilitates automation and maintenance.

Common Specification Formats

There are several standardized formats that make API specifications machine-readable (so tools can process them) and human-readable (so we can understand them). The most widely used for REST APIs is OpenAPI (aka Swagger). Here’s an example of what it looks like.

API Schema

A schema is a subset of a specification that focuses specifically on drilling down the structure of data for machines. In a REST API, a schema might define what the request body or response body should look like—what fields exist, their data types, allowed values, and validation rules—working like a blueprint for those messages.

APIs using OpenAPI or Swagger commonly store their schemas under /openapi.json or /swagger.json. While all APIs have a specification, they might not have a schema.

In API Alchemist, schemas can be imported to streamline feed setup into a single UI.

Bubble, bubble, toil and trouble!

Did this guide help APIs make a little bit more sense? Do you still have any burning potions questions? Let me know in the comments down below. 👇