{ "openapi": "3.1.0", "info": { "title": "Awesome Go package discovery", "version": "1.0.0", "description": "Public read-only reviewed starter catalog for five categories, not the full Awesome Go directory. Unknown or stale evidence remains unknown. Compilation verifies only displayed snippets on recorded targets; advisories are version-specific evidence, not safety guarantees. No authentication. Query URLs <=4096 bytes; unknown or repeated query keys rejected. GET only; responses are no-store. Browser Origin must match NEXT_PUBLIC_SITE_URL. Limits: 120 requests/minute per socket address per process and 5000 active client entries. Ingress should apply per-client limits behind proxies. Comparison retains all selected IDs regardless of limit." }, "servers": [ { "url": "/" } ], "paths": { "/api/v1/packages": { "get": { "operationId": "searchPackages", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 500 } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "http-routing", "database", "logging", "cli", "configuration" ] } }, { "name": "goVersion", "in": "query", "schema": { "type": "string", "pattern": "^(?:go)?1\\.\\d{1,2}(?:\\.\\d{1,2})?$" } }, { "name": "cgo", "in": "query", "schema": { "type": "string", "enum": [ "any", "none" ], "default": "any" } }, { "name": "platforms", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "linux", "windows" ] }, "maxItems": 2 }, "style": "form", "explode": false }, { "name": "license", "in": "query", "schema": { "type": "string", "enum": [ "any", "permissive" ], "default": "any" } }, { "name": "capabilities", "in": "query", "description": "Reviewed capabilities match; explicitly reviewed unsupported capabilities conflict. An unreviewed capability remains unknown.", "schema": { "type": "array", "maxItems": 11, "items": { "type": "string", "enum": [ "routing", "middleware", "json", "postgresql", "sql", "connection-pool", "structured-logging", "subcommands", "flags", "environment", "file-config" ] } }, "style": "form", "explode": false }, { "name": "verifiedOnly", "in": "query", "description": "Requires a current version-matched compiled example and excludes search candidates with any reported unknown evidence, including advisory status even without related filters. Known advisory records leave reachability unknown. Comparisons retain requested packages and report their unknowns.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "default": { "description": "Invalid input (400), forbidden origin (403), missing resource (404), unsupported method (405), oversized URL (414), rate limit (429), or internal error (500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/packages/{id}": { "get": { "operationId": "getPackage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$" }, "description": "Package catalog ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "default": { "description": "Invalid input (400), forbidden origin (403), missing resource (404), unsupported method (405), oversized URL (414), rate limit (429), or internal error (500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/compare": { "get": { "operationId": "comparePackages", "parameters": [ { "name": "ids", "in": "query", "required": true, "style": "form", "explode": false, "schema": { "type": "array", "minItems": 2, "maxItems": 4, "uniqueItems": true, "items": { "type": "string" } } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 500 } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "http-routing", "database", "logging", "cli", "configuration" ] } }, { "name": "goVersion", "in": "query", "schema": { "type": "string", "pattern": "^(?:go)?1\\.\\d{1,2}(?:\\.\\d{1,2})?$" } }, { "name": "cgo", "in": "query", "schema": { "type": "string", "enum": [ "any", "none" ], "default": "any" } }, { "name": "platforms", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "linux", "windows" ] }, "maxItems": 2 }, "style": "form", "explode": false }, { "name": "license", "in": "query", "schema": { "type": "string", "enum": [ "any", "permissive" ], "default": "any" } }, { "name": "capabilities", "in": "query", "description": "Reviewed capabilities match; explicitly reviewed unsupported capabilities conflict. An unreviewed capability remains unknown.", "schema": { "type": "array", "maxItems": 11, "items": { "type": "string", "enum": [ "routing", "middleware", "json", "postgresql", "sql", "connection-pool", "structured-logging", "subcommands", "flags", "environment", "file-config" ] } }, "style": "form", "explode": false }, { "name": "verifiedOnly", "in": "query", "description": "Requires a current version-matched compiled example and excludes search candidates with any reported unknown evidence, including advisory status even without related filters. Known advisory records leave reachability unknown. Comparisons retain requested packages and report their unknowns.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "default": { "description": "Invalid input (400), forbidden origin (403), missing resource (404), unsupported method (405), oversized URL (414), rate limit (429), or internal error (500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/examples/{id}": { "get": { "operationId": "getExample", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,79}$" }, "description": "Package catalog ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Example" } } } }, "default": { "description": "Invalid input (400), forbidden origin (403), missing resource (404), unsupported method (405), oversized URL (414), rate limit (429), or internal error (500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Example": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "packageVersion": { "type": [ "string", "null" ] }, "goVersion": { "type": [ "string", "null" ] }, "verification": { "type": "object", "properties": { "status": { "type": "string" }, "checkedAt": { "type": [ "string", "null" ] }, "targets": { "type": "array", "items": { "type": "string" } }, "cgoEnabled": { "type": "boolean" } } }, "notes": { "type": "array", "items": { "type": "string" } } } }, "Profile": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "modulePath": { "type": "string" }, "importPath": { "type": "string" }, "summary": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "tradeoffs": { "type": "array", "items": { "type": "string" } }, "standardLibrary": { "type": "boolean" }, "source": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "kind": { "type": "string" }, "reviewedAt": { "type": "string" } } }, "metadata": { "type": "object", "properties": { "version": { "type": [ "string", "null" ] }, "goVersion": { "type": [ "string", "null" ] }, "licenses": { "type": [ "array", "null" ], "items": { "type": "string" } }, "dependencies": { "description": "Recorded go.mod Require entries, including declared indirect and test dependencies, or null. This is not a full resolved dependency graph from deps.dev." }, "freshness": { "type": "string", "enum": ["current", "stale"], "description": "Current only when fetchedAt is within the preceding 30 days. Missing, future or expired timestamps are stale. Details, search and examples use effective evidence statuses: expired advisory checks become unknown; expired or version-mismatched compilation becomes unchecked. Historical evidence and dates are retained with an explanatory reason." }, "fetchedAt": { "type": [ "string", "null" ] }, "sourceUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "vulnerabilities": { "type": "object", "properties": { "status": { "type": "string" }, "ids": { "type": "array", "items": { "type": "string" } }, "checkedAt": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } } } }, "example": { "anyOf": [ { "$ref": "#/components/schemas/Example" }, { "type": "null" } ], "description": "Example code is included on details and omitted from search and comparison." } } }, "SearchResult": { "type": "object", "properties": { "catalogVersion": { "type": "string" }, "total": { "type": "integer" }, "results": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Profile" }, { "type": "object", "properties": { "score": { "type": "number" }, "matches": { "type": "array", "items": { "type": "string" } }, "conflicts": { "type": "array", "items": { "type": "string" } }, "unknowns": { "type": "array", "items": { "type": "string" } } } } ] } }, "excluded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } } } } }, "interpretation": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "string" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" } } } } } }