Core Concepts

Core Concepts

Essential API concepts for working with LogZilla's RESTful interface, including HTTP conventions, error handling, pagination mechanisms, and data structures. Understanding these fundamentals enables effective API integration and troubleshooting.

Prerequisites

• Administrative access to LogZilla web interface
• Understanding of REST API concepts and HTTP methods
• JSON data format familiarity
• HTTP client tools (curl, programming language libraries)
• Valid API authentication token (see Getting Started)

HTTP Methods and Conventions

Requests to the API are made using standard HTTP methods. For endpoints that accept or return data in the request/response body, JSON is the standard format, and the user should typically set the Content-Type: application/json header for POST, PUT, and PATCH requests.

Error Handling

The LogZilla API uses standard HTTP status codes to indicate the success or failure of an API request.

2xx (Successful)

• 200 OK: The request was successful.
• 201 Created: The request was successful, and a resource was created.
• 202 Accepted: The request has been accepted for processing, but the processing has not been completed (common for asynchronous operations such as queries). The response body usually contains information on checking the status.
• 204 No Content: The request was successful, but there is no content to return (e.g., for a successful DELETE request).

3xx (Redirection)

• 301 Moved Permanently: The requested resource has been permanently moved to a new location. The response body usually contains the new location. NOTE: this normally means that the user is trying to access the server using HTTP and the server is configured for FORCE_HTTPS==true. The user should use HTTPS instead.

4xx (Client Errors)

• 400 Bad Request: The request could not be understood by the server due to malformed syntax or invalid parameters. The response body often contains more specific error details.
• 401 Unauthorized: Authentication is required and has failed or has not yet been provided. Ensure the auth token is valid and included in the request.
• 403 Forbidden: Authentication was successful, but the authenticated user does not have permission to perform the requested action.
• 404 Not Found: The requested resource could not be found.
• 405 Method Not Allowed: The HTTP method used (e.g., GET, POST) is not supported for the requested resource.
• 408 Request Timeout: The request timed out (often for async operations).
• 429 Too Many Requests: Returned after repeated authentication failures from the same client address (see Security below). The Retry-After header says how many seconds to wait.

5xx (Server Errors)

• 500 Internal Server Error: An unexpected condition was encountered on the server.
• 503 Service Unavailable: The server is currently unable to handle the request due to temporary overloading or maintenance.

When an error occurs, the response body will typically be a JSON object with a detail key:

json
Wrap: OnCopyFullscreen
{"detail": "Error message describing the issue"}

For validation errors (400 Bad Request), the response may include field-specific errors:

json
Wrap: OnCopyFullscreen
{
  "field_name": ["Error message for this field"],
  "another_field": ["Another error message"]
}

For server errors (500), the response may include an error key and optionally a traceback:

json
Wrap: OnCopyFullscreen
{
  "error": "An unexpected error occurred",
  "traceback": "...detailed traceback..."
}

Pagination

LogZilla's API uses different pagination mechanisms depending on the endpoint:

Standard List Pagination (Most Endpoints)

Used for endpoints like /api/users, /api/dashboards, and /api/triggers.

Request: Pass page and page_size as query parameters:

http
Wrap: OnCopyFullscreen
GET /api/users?page=2&page_size=50

Response structure:

json
Wrap: OnCopyFullscreen
{
  "objects": [ ... ],
  "item_count": 157,
  "page_count": 4,
  "page_number": 2
}

Query Results Pagination

Used specifically for the /api/query/{qid} endpoint for event search results.

Request: Pass pagination parameters in the query body or as URL parameters:

json
Wrap: OnCopyFullscreen
{
  "page": 1,
  "page_size": 100,
  "offset": 0
}

Response structure: Pagination info is nested within the results:

json
Wrap: OnCopyFullscreen
{
  "query_id": "...",
  "status": "SUCCESS",
  "results": {
    "events": {
      "objects": [ ... ],
      "page_number": 1,
      "page_size": 100,
      "offset": 0,
      "item_count": 1234,
      "page_count": 13
    }
  }
}

Common Data Structures and Formats

Event Field Names

Events in LogZilla are characterized by several standard fields:

Best Practices

Rate Limiting and Performance

• Use pagination for large result sets
• Cache query IDs for repeated access
• Implement exponential backoff for retries
• Use appropriate page_size values (typically 100-1000)

Security

• Store API tokens securely (environment variables, secrets management)
• Use HTTPS for all API communications
• Implement proper error handling
• Regularly rotate API tokens

Repeated failed logins for one username from one client address lock that username from that address for the rest of a failure window, even when the correct password is supplied. The window starts at the first failure; the defaults are 5 failed logins and a window of 300 seconds. Failed logins, unknown API tokens, and wrong password reset keys (POST /api/reset-password) are counted separately; once an address has produced 30 of one kind within a window, further failures of that kind from that address are answered with 429 Too Many Requests and a Retry-After header. This limit never refuses a correct password, a valid token, or a valid reset key, and it neither counts nor refuses a request for a reset key. Internal LogZilla components and the HTTP event receiver are not affected. The limits are the AUTH_FAILURE_* settings of the Auth and Sessions group, described on the Server Settings page.

Caveats: the client address is the one the LogZilla front proxy accepted the connection from. When one or more additional proxies or load balancers sit in front of LogZilla and append the client address to X-Forwarded-For, set AUTH_TRUSTED_PROXY_HOPS in the Auth and Sessions group to the number of those proxies, and the limits and the login audit charge the address those proxies recorded. Set it only when every request reaches LogZilla through those proxies, because a client that reaches LogZilla directly could then present a forged address. A proxy that does not append the header leaves every user on one shared address, where AUTH_FAILURE_ADDRESS_LIMIT set to 0 and, if the shared account lock is a problem, AUTH_FAILURE_USER_LIMIT set to 0 remain the remedies.

Query Optimization

• Use specific filters to reduce result sets
• Leverage time ranges to limit data scope

References

• Interactive API Documentation (/api/docs on the LogZilla server) - Current and detailed API specifications
• Authentication Guide - Token management and usage
• API Code Examples - Examples of performing API requests with error handling