REST API
A REST (Representational State Transfer) API is a web service interface that uses standard HTTP methods (GET, POST, PUT, DELETE, PATCH) to access and manipulate resources identified by URLs, following a set of architectural conventions that make APIs predictable and interoperable.
Understanding REST API
REST is the dominant architectural style for web APIs. Its conventions — resources identified by URLs, state changes via HTTP methods, stateless requests, and standard response formats — create predictability that makes integration straightforward. Most web services (GitHub, Slack, Notion, Google Workspace, Stripe) expose REST APIs.
RESTful design centers on resources: a task is a resource at /tasks/123, a user is a resource at /users/456. GET /tasks/123 retrieves the task. POST /tasks creates a new task. PUT /tasks/123 replaces the task. PATCH /tasks/123 partially updates it. DELETE /tasks/123 removes it. These conventions mean developers can work with unfamiliar APIs quickly.
REST responses typically use JSON format, which is lightweight, human-readable, and universally supported. Responses include status codes that communicate success (200, 201) or failure (400, 401, 403, 404, 500), enabling robust error handling.
REST has limitations for complex use cases: over-fetching (getting more data than needed), under-fetching (needing multiple calls to get all required data), and lack of real-time capabilities (use webhooks or WebSocket for events). GraphQL addresses some of these limitations for complex data requirements.
How GAIA Uses REST API
GAIA communicates with its integrations primarily through REST APIs. Gmail, Google Calendar, Notion, Slack, Linear, GitHub, and most other connected services expose REST APIs that GAIA queries to read data, create records, and trigger actions.
Related Concepts
API Integration
API integration is the process of connecting different software applications through their Application Programming Interfaces, enabling them to share data and functionality directly.
Webhook
A webhook is an HTTP callback mechanism where a system sends an automated HTTP request to a specified URL whenever a defined event occurs, enabling real-time notification and integration between services without polling.
OAuth
OAuth (Open Authorization) is an open standard for delegated authorization that allows a third-party application to access a user's data in another service without requiring the user to share their password.
Model Context Protocol (MCP)
Model Context Protocol (MCP) is an open standard that enables AI models to securely connect with external tools, data sources, and services through a unified interface.
Idempotency
Idempotency is a property of an operation where executing it multiple times produces the same result as executing it once — making it safe to retry without causing unintended side effects.
