API Overview

The GoodData API is a RESTful API that provides access to all platform features. This documentation covers authentication, endpoints, request/response formats, and integration examples.

Base URL

All API requests should be made to your configured backend base URL:

http://localhost:8000/api

https://api.yourapp.com/api

Authentication

The API uses JWT (JSON Web Token) based authentication. Include the token in the Authorization header for authenticated requests:

Authorization: Bearer <your-jwt-token>

Getting a Token

Obtain a JWT token through the authentication endpoints:

// Login with email/password
const response = await fetch('/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});

const { token, user } = await response.json();

Request Format

Headers

All requests should include these headers:

Content-Type: application/json
Authorization: Bearer <token>  # For authenticated endpoints

Request Body

API requests expect JSON payloads:

{
  "field1": "value1",
  "field2": "value2"
}

Response Format

All API responses follow a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Operation completed successfully"
}

Error Response

{
  "success": false,
  "error": "Error message describing what went wrong",
  "code": "ERROR_CODE",
  "details": {
    // Additional error details (optional)
  }
}

Status Codes

The API uses standard HTTP status codes:

API Endpoints

Authentication

Users

Contact & Communication

Content

Rate Limiting

API requests are rate-limited to ensure service stability:

• Authentication endpoints: 5 requests per minute
• General endpoints: 100 requests per minute
• Bulk operations: 10 requests per minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200

Pagination

List endpoints support pagination using query parameters:

GET /api/users?page=1&limit=20&sort=created_at&order=desc

Pagination Parameters

Pagination Response

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Filtering & Searching

Most list endpoints support filtering and searching:

GET /api/users?search=john&status=active&created_after=2024-01-01

Common Filters

Webhooks

GoodData can send webhooks for important events:

Supported Events

• user.created - New user registration
• user.updated - User profile updated
• contact.submitted - Contact form submission
• newsletter.subscribed - Newsletter subscription

Webhook Format

{
  "event": "user.created",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "user": {
      "id": "user_123",
      "email": "user@example.com",
      "name": "John Doe"
    }
  }
}

SDKs & Libraries

JavaScript/TypeScript

Use the built-in API client:

import { api } from '@/lib/api';

// Authenticate
const { token, user } = await api.login({
  email: 'user@example.com',
  password: 'password123'
});

// Make authenticated requests
const profile = await api.getMe();

cURL Examples

# Login
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

# Get profile (with token)
curl -X GET http://localhost:8000/api/auth/me \
  -H "Authorization: Bearer <your-token>"

Error Handling

Validation Errors

Field validation errors return detailed information:

{
  "success": false,
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "email": ["Email is required", "Email must be valid"],
    "password": ["Password must be at least 8 characters"]
  }
}

Common Error Codes

Testing

Testing Endpoints

Use the following test endpoints in development:

GET /api/health      # Check API health
GET /api/version     # Get API version
GET /api/test        # Test authentication

Postman Collection

Import our Postman collection for easy API testing:

{
  "info": {
    "name": "GoodData API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    // Collection items...
  ]
}

Best Practices

Client Implementation

1. Always handle errors: Check response status and handle error cases
2. Implement retry logic: For network errors and rate limits
3. Cache tokens: Store JWT tokens securely and reuse them
4. Use timeouts: Set reasonable request timeouts
5. Log requests: Log API calls for debugging (without sensitive data)

Security

1. Use HTTPS: Always use HTTPS in production
2. Validate SSL: Verify SSL certificates
3. Store tokens securely: Use secure storage for JWT tokens
4. Rotate tokens: Refresh tokens before expiration
5. Sanitize inputs: Validate and sanitize all user inputs

Support

Need help with the API?

• Authentication Guide - Detailed authentication setup
• Endpoint Reference - Complete endpoint documentation
• Error Reference - Detailed error information
• Contact Support - Get help from our team