This specification outlines the API for a prototype feature management platform. The API provides functionality to create, read, update, delete, and toggle feature flags, as well as managing environments and users.
Authentication is implemented using a simple API key mechanism.
Headers:
Authorization: ApiKey YOUR_API_KEY
https://api.featureflag.example/v1
GET /flags
Query Parameters:
project_id(optional): Filter flags by projectenvironment_id(optional): Filter flags by environmentlimit(optional): Number of items to return (default: 20)offset(optional): Pagination offset (default: 0)
Response:
{
"flags": [
{
"id": "flag-123",
"key": "new-checkout-flow",
"name": "New Checkout Flow",
"description": "Enables the new checkout experience",
"created_at": "2025-04-01T12:00:00Z",
"updated_at": "2025-04-05T15:30:00Z",
"state": {
"dev": true,
"staging": true,
"production": false
},
"tags": ["checkout", "beta"]
}
],
"total": 43,
"limit": 20,
"offset": 0
}GET /flags/{flag_id}
Response:
{
"id": "flag-123",
"key": "new-checkout-flow",
"name": "New Checkout Flow",
"description": "Enables the new checkout experience",
"created_at": "2025-04-01T12:00:00Z",
"updated_at": "2025-04-05T15:30:00Z",
"state": {
"dev": true,
"staging": true,
"production": false
},
"tags": ["checkout", "beta"],
"rules": [
{
"id": "rule-456",
"type": "user",
"attribute": "email",
"operator": "ends_with",
"values": ["@company.com"],
"environment": "staging"
}
]
}POST /flags
Request Body:
{
"key": "new-checkout-flow",
"name": "New Checkout Flow",
"description": "Enables the new checkout experience",
"state": {
"dev": true,
"staging": false,
"production": false
},
"tags": ["checkout", "beta"]
}Response:
{
"id": "flag-123",
"key": "new-checkout-flow",
"name": "New Checkout Flow",
"description": "Enables the new checkout experience",
"created_at": "2025-04-07T12:00:00Z",
"updated_at": "2025-04-07T12:00:00Z",
"state": {
"dev": true,
"staging": false,
"production": false
},
"tags": ["checkout", "beta"]
}PUT /flags/{flag_id}
Request Body:
{
"name": "Updated Checkout Flow",
"description": "Enables the redesigned checkout experience",
"tags": ["checkout", "beta", "redesign"]
}Response:
{
"id": "flag-123",
"key": "new-checkout-flow",
"name": "Updated Checkout Flow",
"description": "Enables the redesigned checkout experience",
"created_at": "2025-04-01T12:00:00Z",
"updated_at": "2025-04-07T14:30:00Z",
"state": {
"dev": true,
"staging": true,
"production": false
},
"tags": ["checkout", "beta", "redesign"]
}PATCH /flags/{flag_id}/state
Request Body:
{
"environment": "staging",
"enabled": true
}Response:
{
"id": "flag-123",
"key": "new-checkout-flow",
"state": {
"dev": true,
"staging": true,
"production": false
},
"updated_at": "2025-04-07T15:45:00Z"
}DELETE /flags/{flag_id}
Response:
204 No Content
POST /flags/{flag_id}/rules
Request Body:
{
"type": "user",
"attribute": "email",
"operator": "ends_with",
"values": ["@company.com"],
"environment": "staging"
}Response:
{
"id": "rule-456",
"type": "user",
"attribute": "email",
"operator": "ends_with",
"values": ["@company.com"],
"environment": "staging",
"created_at": "2025-04-07T16:00:00Z"
}DELETE /flags/{flag_id}/rules/{rule_id}
Response:
204 No Content
GET /environments
Response:
{
"environments": [
{
"id": "env-123",
"key": "dev",
"name": "Development",
"description": "Development environment",
"created_at": "2025-03-01T12:00:00Z"
},
{
"id": "env-456",
"key": "staging",
"name": "Staging",
"description": "Staging/QA environment",
"created_at": "2025-03-01T12:00:00Z"
},
{
"id": "env-789",
"key": "production",
"name": "Production",
"description": "Production environment",
"created_at": "2025-03-01T12:00:00Z"
}
]
}POST /environments
Request Body:
{
"key": "beta",
"name": "Beta",
"description": "Beta test environment"
}Response:
{
"id": "env-101",
"key": "beta",
"name": "Beta",
"description": "Beta test environment",
"created_at": "2025-04-07T17:00:00Z"
}DELETE /environments/{environment_id}
Response:
204 No Content
GET /sdk/config?environment={environment_key}
Response:
{
"environment": "production",
"flags": {
"new-checkout-flow": false,
"dark-mode": true,
"recommendation-engine": true
},
"updated_at": "2025-04-07T18:00:00Z"
}POST /sdk/evaluate
Request Body:
{
"environment": "production",
"user": {
"id": "user-123",
"email": "john@company.com",
"groups": ["beta-testers"],
"country": "US"
}
}Response:
{
"environment": "production",
"flags": {
"new-checkout-flow": true,
"dark-mode": true,
"recommendation-engine": true
},
"evaluated_at": "2025-04-07T18:05:00Z"
}POST /analytics/exposure
Request Body:
{
"flag_key": "new-checkout-flow",
"environment": "production",
"user_id": "user-123",
"timestamp": "2025-04-07T18:10:00Z",
"client_id": "web-app"
}Response:
204 No Content
GET /analytics/flags/{flag_id}/stats?environment={environment_key}&period=7d
Response:
{
"flag_id": "flag-123",
"flag_key": "new-checkout-flow",
"environment": "production",
"period": "7d",
"exposures": {
"total": 15420,
"breakdown": {
"2025-04-01": 2105,
"2025-04-02": 2211,
"2025-04-03": 2098,
"2025-04-04": 2245,
"2025-04-05": 2301,
"2025-04-06": 2198,
"2025-04-07": 2262
}
}
}All endpoints return appropriate HTTP status codes:
200 OK: The request was successful201 Created: The resource was created successfully204 No Content: The request was successful, with no response body400 Bad Request: The request was invalid401 Unauthorized: API key is missing or invalid403 Forbidden: The API key doesn't have permission for the requested operation404 Not Found: The requested resource was not found409 Conflict: The request conflicts with current state (e.g., duplicate key)429 Too Many Requests: Rate limit exceeded500 Internal Server Error: An error occurred on the server
Error response body:
{
"error": {
"code": "invalid_request",
"message": "Flag key must be unique",
"details": {
"field": "key",
"constraint": "unique"
}
}
}API requests are limited to 100 requests per minute per API key. Rate limit information is included in the response headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1617807600