ADR-0012: HTTP Methods for SPIKE API

Status: accepted
Date: 2024-11-04
Tags: API, TLS, Semantics, Network, Operations

Context

SPIKE is a secrets management system that provides an HTTP API for CRUD operations. The system integrates with SPIFFE/SPIRE for identity management and authentication.

When designing the API, we needed to determine how to handle HTTP methods for different operations while maintaining security and preventing unwanted caching of sensitive data.

Key considerations:

Prevention of URL caching for security purposes
Desire for consistent request structure
Need to maintain semantic clarity of operations
Integration with proxy servers and security infrastructure
Auditability and debugging capabilities

Decision

We will:

Use HTTP POST method for all API operations (Create, Read, Update, Delete)
Encode the operation type in the URL query parameter using action=
Include all operation parameters in the request body

Example URLs:

https://host:port/v1/secrets?action=read
https://host:port/v1/secrets?action=delete
https://host:port/v1/secrets?action=write

Consequences

Positive

Prevents sensitive data from being cached in URLs
Avoids sensitive data appearing in server logs
Provides consistent request structure for all operations
Simplifies client implementations by using uniform HTTP method
Makes operation type visible in URL for auditing without exposing sensitive data
Works well with proxies that might restrict certain HTTP methods
Maintains clear operation semantics through URL parameters

Negative

Deviates from REST architectural principles
May surprise developers expecting traditional REST endpoints
Could complicate integration with some REST-focused tools
URL routing slightly more complex due to query parameter handling

Neutral

Operation type moved to query parameter instead of HTTP method
Need to handle invalid/missing action parameters

Alternatives Considered

Traditional REST approach with different HTTP methods

Rejected due to caching concerns and desire for consistency

Using path parameters instead of query parameters

/v1/secrets/read
/v1/secrets/delete

Rejected to maintain existing implementation pattern

GraphQL-style single endpoint

Rejected as overly complex for current needs

Compliance

This decision maintains compliance with security best practices while providing a usable API interface. It aligns with the security-first approach required for a secrets management system.