API Documentation for Beta Catalog and Harvest

[SueValente]

User Story

In order to programmatically access data.gov resources, developers want comprehensive API documentation (similar to Swagger UI) that explains endpoints, request methods, query parameters, and resource counting methodology.

Acceptance Criteria

• GIVEN a developer wants to use the beta catalog API
  WHEN they visit the API documentation
  THEN they see Swagger-style documentation with supported endpoints, request methods, and query parameters

• GIVEN a developer wants to use the harvest API
  WHEN they visit harvest.data.gov documentation
  THEN they see comprehensive API documentation similar to catalog-beta

• GIVEN a developer notices discrepancy in resource counts
  WHEN they review API documentation
  THEN the documentation explains how resources are counted (individual data assets vs collections) and why CKAN API shows ~391K while front page shows 511K

• GIVEN a developer is migrating from old API
  WHEN they review documentation
  THEN they understand differences in resource counting between old and new systems

Background

Source: External beta feedback from Chris Marcum (christopher.steven.marcum@gmail.com) - 1/26/2026 and Berk Bayer (DOI) - 1/27/2026

Current gaps:

• No comprehensive API documentation for catalog-beta.data.gov
• No API documentation for harvest.data.gov
• Resource counting methodology not documented (391K vs 511K discrepancy)
• Developers can't easily understand how to resolve individual data asset counts
• Collections with multiple data assets used to count as one resource, now each asset counts individually

User needs:

• Swagger-style API documentation
• Clear explanation of resource counting
• Documentation for both catalog-beta and harvest APIs
• Migration guide from old to new API structure

Security Considerations

Ensure API documentation does not expose sensitive endpoints or internal system details that could be exploited. Document only public-facing API capabilities.

Sketch

• Audit current API endpoints for catalog-beta.data.gov
• Audit current API endpoints for harvest.data.gov
• Create Swagger/OpenAPI specification documents
• Document resource counting methodology and explain 391K vs 511K difference
• Create developer-friendly documentation pages
• Include example requests and responses
• Explain collection vs individual asset counting
• Consider hosting Swagger UI interface for interactive exploration
• Link to documentation from main site navigation