Skip to main content

API Conventions

Standard patterns and conventions used throughout the Infino API.

HTTP Methods and Semantics​

Standard REST Methods​

  • GET: Retrieve data without side effects
    • Searches, index metadata, document retrieval
    • Safe for caching and retry
    • No request body (use query parameters)
  • POST: Create resources or execute operations
    • Bulk ingest, complex queries, SQL queries
    • May have side effects
    • Request body contains operation data
  • PUT: Create or replace resources idempotently
    • Index creation, document indexing with ID
    • Safe to retry (idempotent)
    • Full resource replacement semantics
  • DELETE: Remove resources
    • Index deletion, document removal
    • Idempotent operation
  • HEAD: Check resource existence
    • Document existence checks
    • Returns only headers, no body

Method Usage Patterns​

# Retrieval operations
GET /{dataset}/querydsl
GET /metadata
GET /{dataset}/metadata

# Creation operations  
PUT /{dataset}
POST /{dataset}/json
POST /sql

# Deletion operations
DELETE /{dataset}

Request and Response Formats​

Content Types​

  • Default: application/json
  • Bulk operations: application/x-ndjson (newline-delimited JSON)
  • Form data: application/x-www-form-urlencoded (for some query APIs)
  • SQL queries: application/json with query in body

Character Encoding​

  • All text: UTF-8 encoding
  • Content-Type header: Should include charset when applicable
  • Binary data: Base64 encoded within JSON

Request Headers​

Content-Type: application/json
Authorization: AWS4-HMAC-SHA256 Credential=...
X-Amz-Date: 20240115T103000Z
X-Amz-Content-Sha256: abc123...

Response Headers​

Content-Type: application/json; charset=utf-8
Content-Length: 1234
X-Request-ID: req_abc123def456

Index Naming Conventions​

Index names must follow specific rules for valid characters, length limits, and reserved prefixes.

Complete Dataset Naming Rules

For detailed dataset naming conventions, examples, and reserved system indexes, see Dataset Management → Dataset Naming Conventions.

Data Types and Formats​

Timestamps​

  • Format: ISO 8601 with UTC timezone
  • Examples:
    • 2024-01-15T10:30:00Z
    • 2024-01-15T10:30:00.123Z (with milliseconds)
  • Parsing: Accepts various formats, returns standardized format
  • Range: Unix epoch to year 2038+ support

Numbers​

  • Integers: JSON number format, 64-bit precision
  • Floats: Double precision floating point
  • Special values: null for missing, no NaN or Infinity
  • Ranges: Standard JSON number limits

Text and Strings​

  • Encoding: UTF-8 only
  • Length limits: Configurable per field, default 32KB
  • Null handling: Use JSON null, not empty strings for missing data
  • Escaping: Standard JSON string escaping rules

Booleans​

  • Values: true or false (lowercase)
  • No coercion: Strings like "true" not automatically converted

Arrays and Objects​

  • Arrays: Homogeneous types preferred, mixed types supported
  • Objects: Nested objects supported with depth limits
  • Null values: Preserved in arrays and objects

Binary Data​

  • Encoding: Base64 within JSON strings
  • Size limits: 16MB default limit for binary fields
  • MIME types: Store separately if needed for content type detection

Pagination and Limits​

Standard Pagination​

{
  "from": 10,
  "size": 20,
  "hits": {
    "total": {"value": 150},
    "hits": [...]
  }
}

Parameters​

  • from: Zero-based offset (no default, optional)
  • size: Number of results to return (default: 10)
  • Maximum size: 10,000 results per request (MAX_SIZE_DEFAULT)
  • Deep pagination: Use search_after for large offsets

Search After for Large Datasets​

{
  "size": 1000,
  "query": {"match_all": {}},
  "sort": [{"@timestamp": "desc"}],
  "search_after": ["2024-01-15T10:30:00.000Z"]
}

Pagination Types​

  • Offset pagination: Use from and size parameters
  • Cursor pagination: Use search_after with timestamp or document ID
  • Default behavior: No from specified returns results from beginning

Rate Limits​

  • Default: No hard rate limits
  • Bulk operations: Optimized for high throughput
  • Complex queries: May have dynamic throttling
  • Headers: Rate limit info in response headers when applicable

Headers and Metadata​

Standard Headers​

  • Authorization: AWS Signature V4 (required)
  • Content-Type: Request body format
  • Accept: Response format preference
  • User-Agent: Client identification

Custom Headers​

  • X-Request-ID: Request correlation (auto-generated if not provided)
  • X-Request-Timeout: Override default timeout
  • X-Trace-ID: Distributed tracing correlation

Response Headers​

  • X-Request-ID: Request correlation ID
  • X-Response-Time: Server processing time in milliseconds
  • X-Node-ID: Processing node identifier (for debugging)

Security and Access Patterns​

Authentication Flow​

  1. All requests require AWS Signature V4
  2. Invalid signatures result in 401 responses
  3. Expired signatures (>15 minutes) are rejected
  4. Credentials are validated against account permissions

Authorization Model​

  • Account-based: All operations scoped to authenticated account
  • Index-level: Permissions can be restricted per index
  • Operation-level: Read vs write permissions
  • Field-level: Sensitive field access controls

HTTPS Requirements​

  • TLS 1.2+: Minimum required version
  • Certificate validation: Clients should validate server certificates
  • HSTS: HTTP Strict Transport Security enabled
  • Redirect policy: HTTP requests redirected to HTTPS

This comprehensive documentation covers all the patterns and conventions developers need to understand when working with the Infino API.