API Overview and Integration Guidelines

Introduction

The Publica.la REST API provides comprehensive integration capabilities for your digital publishing platform. Our API is designed specifically for server-to-server communication and backend integrations, offering robust tools to manage content, users, orders, plans, reading permissions, and authentication sessions.

This documentation covers everything you need to integrate securely and efficiently with our platform, including authentication requirements, rate limiting, CORS policies, and security best practices.

API Resources Overview

Our API provides access to these core resources:

• Content: Manage publications, issues, and digital content
• Orders: Process purchases and transaction data
• Plans: Manage subscription plans and pricing
• Users: Handle user accounts and profiles
• Reading Permissions: Control access to content
• Auth Sessions: Monitor and manage user sessions

Getting Started

1. Generate your API token from Dashboard > Settings > Integrations
2. Choose your integration approach
3. Set up authentication with the X-User-Token header
4. Test basic functionality with a simple GET request
5. Implement error handling for production usage
6. Monitor rate limits and optimize request patterns

For specific endpoint documentation, select the resource you need from the navigation menu.

API Architecture and Design Principles

Backend-Only Integration

Our REST API is designed exclusively for backend integrations. This architectural decision ensures:

• Enhanced Security: API tokens never leave your secure server environment
• Reliable Performance: No client-side limitations or browser restrictions
• Scalable Operations: Optimized for high-volume automated processes

Never Expose API Tokens on Client Side

NEVER include API tokens in frontend code, mobile applications, or any client-accessible environment. Tokens must remain secure on your backend servers only.

If you suspect your API token has been compromised, you can immediately delete or regenerate it by going to Dashboard > Settings > Integrations in your store.

Base URL Structure

All API endpoints operate based on your store's domain:

https://{your-store-domain}/integration-api/v1/

Example: If your store domain is example.publica.la, your API base URL is:

https://example.publica.la/integration-api/v1/

Authentication

Generating API Tokens

Before using the API, you must generate an authentication token:

1. Access your store dashboard: Go to Dashboard > Settings > Integrations
2. Generate API key: In the API Integration Key section, click Generate new key
3. Secure your token: Copy and store the token securely in your backend environment

Administrative Access

API keys can be generated by admin users only. Each admin can generate their own unique token.

Making Authenticated Requests

Include your API token in every request using the X-User-Token header:

GET /integration-api/v1/users
Content-Type: application/json
Accept: application/json
X-User-Token: your_api_token_here

Required Headers:

{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "X-User-Token": "your_api_token_here"
}

Rate Limiting and Flood Protection

Rate Limiting Configuration

Our API implements rate limiting to ensure platform stability and fair resource allocation. All API endpoints require authentication and are limited to 60 requests per minute per API token.

Rate Limiting Headers

Monitor your usage through these response headers:

Header	Description	Example
X-RateLimit-Limit	Total allowed requests per minute	60
X-RateLimit-Remaining	Requests left in current window	45
X-RateLimit-Reset	When limits reset (UNIX timestamp)	1666897200

Rate Limit Reset

X-RateLimit-Reset header appears only when limits are exhausted, showing when the window will reset.

Rate Limit Response Example

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1666897200

# When limit exceeded:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1666897320

Security Features

Security Headers

All API responses include security headers:

Strict-Transport-Security: max-age=31536000; includeSubdomains
X-Content-Type-Options: nosniff
X-XSS-Protection: 1

Request Logging and Monitoring

• Comprehensive logging: All API requests are logged for security and debugging
• IP tracking: Request origins are monitored for abuse detection
• Audit trails: Complete audit logs for compliance and troubleshooting

Data Validation and Error Handling

Input Validation

All API endpoints implement strict validation:

• Type checking: Parameters must match expected data types
• Range validation: Numeric values must fall within acceptable ranges
• Format validation: Strings must match required patterns (emails, URLs, etc.)
• Required fields: Missing required parameters return clear error messages

Error Response Format

Errors follow a consistent format:

{
  "CODE": "error",
  "message": "Detailed error description",
  "errors": {
    "field_name": ["Specific validation error"]
  }
}

HTTP Status Codes

Code	Meaning	Usage
200	Success	Request completed successfully
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Invalid or missing API token
404	Not Found	Resource doesn't exist
422	Validation Error	Request validation failed
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Integration Best Practices

Performance Optimization

1. Implement caching: Cache responses appropriately on your end to reduce API calls
2. Monitor rate limits: Always check rate limiting headers in responses
3. Implement backoff: Use exponential backoff when approaching limits
4. Distribute requests: Spread API calls over time rather than bursts

Security Best Practices

1. Secure token storage: Store API tokens in secure environment variables
2. HTTPS only: Always use HTTPS for API requests
3. Validate responses: Always validate API response data

---