Handle API changes before they reach your public data table

Before refreshing an API-fed spreadsheet or public data page, check that the new response still produces the table readers expect. A successful request is not enough: the export also needs the right columns, complete coverage and unchanged—or clearly documented—definitions.

Use this workflow to turn an upstream API response into a reviewed CSV. The intended result is a stable public table, with a release note when something meaningful changes.

Which API changes matter to a dataset?

A breaking change can make an existing integration stop working. GitHub’s REST API documentation lists examples such as renamed response fields, changed field types, new required parameters and changed authentication requirements. It classifies added response fields and optional parameters as additive changes. Those are GitHub’s rules, not a guarantee for every provider. GitHub API versioning documentation

For data publishing, also check changes that affect interpretation or completeness:

Change	What to check before publishing
A field is renamed or removed	Does the export still populate every required column?
Numbers arrive as strings	Are measure columns parsed correctly while identifiers retain leading zeroes?
Pagination or sorting changes	Did you retrieve every page without duplicate or omitted records?
Date boundaries or frequency change	Does the export still cover the intended periods?
Units, categories or definitions change	Are old and new values still comparable?
Access requirements change	Can the collection job retrieve the intended dataset with its approved credentials?

These are not only hypothetical risks. EIA’s API patch notes document string-valued data in January 2024, default sorting in September 2025, revised date-boundary behavior in January 2026 and a correction to reported row totals in March 2026. A workflow can change even while its route remains under /v2/. EIA API technical documentation

1. Define the table you promise readers

Do not let the raw API response dictate your public columns on every refresh. Write down an output schema: the column names, types and meanings your published table must retain.

For example, this illustrative monthly dataset could use:

Column	Required rule	Illustrative value
region_id	Text identifier; preserve leading zeroes	01
period	Month in YYYY-MM format	2026-09
value	Decimal measure, or a documented missing value	12.4
unit	Explicit measurement unit	index_points

Define the row key too. In this example, require one row per region_id and period; if you add multiple measures, include the measure identifier in that key.

Keep the conversion from source fields to public columns in a separate mapping. If an upstream field is renamed, update that mapping rather than silently renaming the public column. Select columns by name, not position, and explicitly allow only the fields intended for publication.

2. Record the request and check the provider’s change log

Keep a private collection record containing:

• Provider and endpoint.
• Requested API version, where supported.
• Filters, date bounds, frequency and sorting.
• Pagination method and retrieval time.
• Mapping or transformation version.

Exclude credentials from shared records and public source links.

Specify a supported API version when the provider offers that option, but do not treat version selection as a complete freeze. GitHub, for example, makes additive changes available across supported versions and documents exceptions for urgent security or reliability issues. GitHub’s versioning policy

3. Validate a candidate export before replacing the published file

Run the new response through the mapping, then check:

• Structure: all required columns exist and have the expected types.
• Completeness: every page was retrieved; date and geographic coverage match the request.
• Uniqueness: no duplicate row keys.
• Meaning: units, categories and missing-value conventions match the published documentation.
• Differences: compare row counts, period coverage, missing-value rates and key totals with the last reviewed export.

For EIA specifically, JSON responses are limited to 5,000 rows per request; its documentation directs users to constrain requests or paginate with offset. Do not mistake one full response for the complete dataset. EIA pagination guidance

Investigate differences rather than rejecting every change: a legitimate source revision may alter historical values. Stop publication when a difference is unexplained. For ongoing checks, see API monitoring for public dataset workflows.

4. Publish the reviewed table and its release note

Export only approved public fields. TablePage accepts CSV, TSV, XLSX and XLS files and generates a public dataset page with a shareable link and filterable table. Upload a reviewed file—not a raw response containing credentials or sensitive information. TablePage

Keep the previous reviewed export as a fallback. Accompany the new release with its source link, retrieval date, coverage, units and missing-value convention. Note whether the change affected only collection code or also changed values, coverage or definitions.

If validation fails, leave the last reviewed dataset available and disclose its actual data date. An older, accurately labeled table is preferable to presenting an unchecked refresh as current.