Using the API

Overview

Using the API requires an API key. If you do not have an API key, you can request one from HYAS Support via one of the mechanisms below. 

A variety of pre-built integrations exist -- to utilize them, make sure you have the partner product installed and connect it with your HYAS API key. Documentation exists for building your own custom integration, starting with HYAS Protect API Documentation which provides an overview of the HYAS Protect API endpoints via a Swagger Document.

HYAS Protect API Best Practices

This guide outlines recommended practices for integrating with and consuming the HYAS Protect APIs. It complements the HYAS Protect Swagger documentation and is intended for developers, security engineers, and DevOps professionals.

1. Authentication & Access Control

• Secure API Key Usage: Store keys in a secure secrets management system (e.g., HashiCorp Vault), not in code repositories or shared files.

• Use Least Privilege: Apply the minimum necessary scope to each API key.

• Monitor Usage: Log API key activity and alert on anomalous usage patterns.

2. Endpoint Usage

• Correct Endpoint Selection: Use endpoints like /domain/verdict, /ip/verdict, or /fqdn/verdict based on the data you're analyzing.

• Pagination: For endpoints returning log data, use pagination parameters (page, pageSize, startTime, endTime) to manage volume.

• Efficient Queries: Limit results by using appropriate filters and avoid over-fetching data.

3. Security Practices

• HTTPS Only: Always access the API via https://api.hyas.com. Do not use unencrypted HTTP.

• Certificate Validation: Ensure your HTTP client validates the server's TLS certificate.

• Input Sanitization: Validate and sanitize inputs to the API to prevent injection risks.

• Rate Limiting: Respect the rate limits. Implement exponential backoff on 429 Too Many Requests and retryable errors.

4. Error Handling

• Standard Error Processing: Handle HTTP error codes with clear logic. Treat 4xx (except 429) as fatal; retry on 429 and 5xx.

• Logging Failures: Record error messages and codes for troubleshooting.

• Graceful Degradation: If an API dependency fails, continue core functionality where possible and raise alerts.

5. Logging & Monitoring

• Log Each API Call: Include endpoint, status, response time, and key (if permissible).

• Track Metrics: Measure call volume, error rates, and latency.

• Alerting: Set alerts on unexpected failures, API unavailability, or performance degradation.

6. Data Management

• Cursor-based Pagination: Use cursors or tokens (if supported) to handle large result sets and resume from the last known state.

• Offset Tracking: Maintain the last retrieved page or offset to ensure continuity after a failure or restart.

7. Timeout & Retry Strategy

• Set Timeouts: Use appropriate client timeouts (e.g., 10–30 seconds) to avoid hanging connections.

• Exponential Backoff: On transient errors, retry requests with increasing delays.

• Failover Handling: Detect long-running API outages and notify operations teams or degrade functionality.

8. Integration Workflows

• SIEM/SOAR Enrichment: Use verdict APIs to add threat intelligence context to alerts.

• Automated Mitigation: Integrate verdict results into playbooks that take action (e.g., blocking domains via firewalls).

• Log Correlation: Use DNS logs retrieved from the API to enrich investigations and timeline analysis.

9. Performance Optimization

• Batch Retrieval: Use bulk or batch-capable endpoints to reduce overhead.

• Caching: Cache frequent verdict responses for short durations (e.g., 5–10 minutes) to minimize repeated lookups.

• Efficient Resolution: Ensure DNS configurations use HYAS Anycast resolvers for optimal performance.

10. Version Management

• Track Releases: Follow HYAS release notes and Swagger updates for version changes or deprecated endpoints.

• Configurable Versioning: Design clients to easily switch between API versions.

• Deprecation Planning: Update your integrations in line with the deprecation schedule.

11. Documentation and Support

• Swagger Reference: Always confirm request/response schemas via HYAS Protect Swagger docs.

• Internal Documentation: Maintain team-accessible docs that include usage patterns, known limitations, and common response structures.

• Support Engagement: Contact HYAS Support for assistance with unexpected behaviors, undocumented responses, or integration troubleshooting.

Summary