API Overview

API Overview

The Gateway REST API provides comprehensive access to integration management, order synchronization, and platform connectivity. This page provides an overview of the API structure, capabilities, and usage patterns.

Base URL

All API requests are made to:

https://<GATEWAY_URL>/api

Where <GATEWAY_URL> is your Gateway deployment domain.

API Versions

The Gateway API has two versions:

Version	Prefix	Status	Primary Use
1.0	/api/1.0/*	Legacy	User-based operations, backwards compatibility
2.0	/api/2.0/*	Current	Modern endpoint structure, recommended for new integrations

[!IMPORTANT] All new integrations should use API v2.0. Version 1.0 is maintained for backwards compatibility only.

Learn more about API versioning →

---

Endpoint Groups

The Gateway API is organized into three main endpoint groups:

1. USER Endpoints (/api/2.0/user/*)

Authentication: Password Grant OAuth2 (auth:api)

Purpose: User management and OAuth client administration

Common Operations:

• Manage users (CRUD)
• Create OAuth clients -Configure apps and services
• Claim integrations

Example:

GET /api/2.0/user/apps

View authentication details →

---

2. APP Endpoints (/api/2.0/app/*)

Authentication: Client Credentials Grant (client_credentials + auth.app)

Purpose: Application-level integration management

Common Operations:

• List and manage integrations
• Execute integration actions
• Manage accounts
• Create intent tokens
• View services and flows

Example:

GET /api/2.0/app/integrations
POST /api/2.0/app/integrations/{id}/action

Explore app functions →

---

3. WEBCOMPONENT Endpoints (/api/2.0/webcomponent/*)

Authentication: Account-based (auth.account:webcomponent:*)

Purpose: Account-scoped operations for embedded web components

Common Operations:

• List account integrations
• Install/uninstall integrations
• Manage schedules
• View logs
• Upload logos

Example:

GET /api/2.0/webcomponent/integrations
POST /api/2.0/webcomponent/integrations/{id}/install

---

Request Format

Headers

All requests must include:

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

Request Body

For POST, PUT, and PATCH requests, send data as JSON:

{
  "name": "My Shopify Integration",
  "shop": "mystore.myshopify.com"
}

---

Response Format

Success Response

All successful responses return JSON:

{
  "data": {
    "id": 1,
    "name": "Shopify",
    "type": "SHOPIFYV2"
  }
}

For list endpoints, data is an array with pagination metadata:

{
  "data": [
    { "id": 1, "name": "Integration 1" },
    { "id": 2, "name": "Integration 2" }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 2,
    "per_page": 15,
    "total": 50,
    "last_page": 4
  },
  "links": {
    "first": "https://<GATEWAY_URL>/api/2.0/app/integrations?page=1",
    "last": "https://<GATEWAY_URL>/api/2.0/app/integrations?page=4",
    "prev": null,
    "next": "https://<GATEWAY_URL>/api/2.0/app/integrations?page=2"
  }
}

Error Response

Errors return appropriate HTTP status codes with descriptive messages:

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "shop": ["The shop field is required."]
  }
}

---

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded, no content returned
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource not found
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

---

Pagination

List endpoints support pagination via query parameters:

Request:

GET /api/2.0/app/integrations?page=2&per_page=25

Query Parameters:

• page - Page number (default: 1)
• per_page - Items per page (default: 15, max: 100)

Response includes navigation links:

{
  "links": {
    "first": "?page=1",
    "last": "?page=10",
    "prev": "?page=1",
    "next": "?page=3"
  }
}

---

Rate Limiting

API requests are rate-limited based on authentication method:

Authentication Method	Limit
Password Grant	60 requests/minute
Client Credentials	100 requests/minute
Account Token	120 requests/minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1640000000

When rate limited, you’ll receive:

{
  "message": "Too Many Requests"
}

HTTP Status: 429 Too Many Requests

---

Data Formats

Timestamps

All timestamps use ISO 8601 format in UTC:

2024-01-15T10:30:00.000000Z

Boolean Values

Use JSON boolean values:

{
  "active": true,
  "mutable": false
}

Null Values

Nullable fields return null when empty:

{
  "description": null
}

---

Common Patterns

Filtering

Some endpoints support filtering:

GET /api/2.0/app/integrations?status=ACTIVE

Sorting

Use sort parameter where supported:

GET /api/2.0/app/integrations?sort=-created_at

• field - Ascending order
• -field - Descending order

Including Related Data

Some endpoints support including related resources:

GET /api/2.0/app/integrations?include=service,schedules

---

Idempotency

Some operations are idempotent by nature:

• GET - Always idempotent
• PUT - Idempotent (full resource replacement)
• DELETE - Idempotent (deleting already-deleted resource returns 404)
• POST - Generally NOT idempotent (creates new resources)

For critical POST operations, use unique identifiers to prevent duplicates.

---

CORS

The Gateway API supports Cross-Origin Resource Sharing (CORS) for browser-based applications.

Allowed headers:

• Authorization
• Content-Type
• Accept
• X-Requested-With

---

Interactive Documentation

Explore the API interactively using Swagger UI:

Open API Documentation →

Features:

• 🧪 Test endpoints directly from browser
• 📋 View complete request/response schemas
• 🔐 Built-in authentication
• 📚 Comprehensive endpoint documentation

---

SDK and Libraries

Official Libraries

Currently, the Gateway does not provide official SDKs. However, the REST API can be easily consumed using standard HTTP libraries:

PHP:

• Guzzle HTTP Client
• Laravel HTTP Client

JavaScript:

• Axios
• Fetch API
• Node.js https module

Python:

• requests
• httpx

Code Examples

See the Getting Started guide for code examples in multiple languages.

---

Best Practices

1. Use API v2.0

Always use v2.0 endpoints for new integrations:

✅ Good: GET /api/2.0/app/integrations

❌ Avoid: GET /api/1.0/integrations

2. Handle Errors Gracefully

Always check HTTP status codes and handle errors:

try {
  const response = await axios.get('/api/2.0/app/integrations');
  console.log(response.data);
} catch (error) {
  if (error.response.status === 401) {
    // Refresh token
  } else if (error.response.status === 422) {
    // Handle validation errors
    console.error(error.response.data.errors);
  }
}

3. Respect Rate Limits

Implement exponential backoff when rate limited:

async function retryWithBackoff(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.response?.status === 429 && i < retries - 1) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
      } else {
        throw error;
      }
    }
  }
}

4. Cache Responses

Cache static data like services and service configurations:

const cache = new Map();

async function getServices() {
  if (cache.has('services')) {
    return cache.get('services');
  }

  const response = await axios.get('/api/2.0/app/services');
  cache.set('services', response.data, { ttl: 3600 });
  return response.data;
}

5. Use Appropriate HTTP Methods

Follow REST semantics:

• GET - Retrieve data (no side effects)
• POST - Create new resources
• PUT - Full resource update
• PATCH - Partial resource update
• DELETE - Remove resources

---

Next Steps

• Learn about authentication →
• Understand API versioning →
• Explore all endpoints →
• View interactive docs →