REST API Fundamentals
Before building an integration, it helps to understand the core concepts behind REST APIs. If you're already comfortable with REST, skip to Finding API Documentation.
What Is a REST API?
A REST API (Representational State Transfer Application Programming Interface) is a standardized way for two systems to communicate over the internet. Think of it as a structured conversation:
- Your system (Vantage) sends a request — "Give me the current weather in London"
- The other system (the API) sends a response — a structured data package with the answer
Every REST API interaction follows this request → response pattern.
HTTP Methods
HTTP methods tell the API what you want to do with a resource. The API Builder supports four:
| Method | Purpose | Real-World Analogy | Example |
|---|---|---|---|
| GET | Retrieve data | Looking up a contact in your phone | Fetch a list of customers |
| POST | Create new data | Adding a new contact | Create a new order |
| PUT | Update existing data | Editing a contact's phone number | Update a customer's address |
| DELETE | Remove data | Deleting a contact | Remove a cancelled order |
Tip: Most integrations start with GET requests — pulling data into Vantage for analysis. You'll use GET far more often than the other methods.
URLs: Base URL + Path
Every API request goes to a specific URL, which has two parts:
https://api.example.com/v1 + /users/42
Base URL Path
- Base URL — The root address of the API. It stays the same for every request to that service. You enter this once in the API Builder.
- Path — The specific resource you want. Each endpoint has its own path. You define these per endpoint.
Path parameters are dynamic parts of the path, wrapped in curly braces:
/users/{id} → /users/42
/orders/{orderId} → /orders/A-1001
When the integration runs, Vantage replaces {id} with the actual value you provide.
Authentication
Most APIs require proof that you're allowed to use them. The API Builder supports four authentication methods:
| Auth Type | How It Works | When to Use |
|---|---|---|
| API Key (Custom Header) | Sends a key in a custom HTTP header (e.g., X-API-Key: abc123) | When the API docs say to send a key in a specific header |
| Bearer Token | Sends a token as Authorization: Bearer <token> | The most common method for modern APIs (OAuth, JWT) |
| Basic Auth | Sends a username and password encoded in the Authorization header | Older APIs or internal services |
| No Auth | No credentials sent | Public APIs with no access control |
How do you know which to use? The API's documentation will tell you. Look for a section labeled "Authentication", "Authorization", or "Getting Started" — it will specify exactly what's required.
Why does the API Builder ask for auth type separately from credentials? Security. The type is part of the integration definition (shared structure), but the credentials (your actual API key or token) are stored separately with encryption. This means you can share an integration design across your team while credentials remain private.
Request Parameters
Parameters are extra information you send with a request. They can live in four different places:
| Location | What It Looks Like | Example | When to Use |
|---|---|---|---|
| Query | Appended to the URL after ? | GET /users?limit=10&page=2 | Filtering, pagination, sorting |
| Path | Embedded in the URL path | GET /users/{id} → GET /users/42 | Identifying a specific resource |
| Header | Sent as an HTTP header | X-Custom-Header: value | API keys (some APIs), versioning, content negotiation |
| Body | Sent in the request payload | JSON object with the data | Creating or updating data (POST, PUT) |
Tip: GET requests almost always use query and path parameters. POST and PUT requests typically send data in the body.
JSON Responses
APIs return data in JSON (JavaScript Object Notation) — a structured text format that both humans and machines can read:
{
"name": "Acme Corp",
"revenue": 1250000,
"active": true,
"address": {
"city": "Austin",
"state": "TX"
},
"products": [
{ "name": "Widget A", "price": 29.99 },
{ "name": "Widget B", "price": 49.99 }
]
}Key concepts:
- Objects are wrapped in
{ }and contain key-value pairs - Arrays are wrapped in
[ ]and contain lists of items - Nesting — objects can contain other objects or arrays, creating a tree structure
- Dot notation describes paths through the tree:
address.city→"Austin",products[0].name→"Widget A"
Understanding JSON structure is essential for the endpoint definition step, where you map response data to workflow outputs.
Next Steps
- Finding API Documentation — Where to gather the information you need before building