The Problem

Projects that need a vetted list of free public APIs often have to search disparate sources, verify data formats, and check link health manually. Maintaining that list without automated validation quickly becomes error‑prone and time‑consuming.

What This Does

The repository supplies a curated markdown catalog (root README.md) and a small Python validation suite under scripts/.

  • scripts/validate/format.py checks each entry’s title, description, authentication tag, HTTPS usage, CORS header, alphabetical ordering and category consistency.
  • scripts/validate/links.py extracts URLs from the markdown, deduplicates them, and performs a live HTTP GET to confirm the link is reachable.
  • Test modules in scripts/tests/ (test_validate_format.py, test_validate_links.py) exercise the validation logic with a range of edge cases.

How It Is Wired

Execution begins at the main function in scripts/validate/format.py (line 254). From there it calls a chain of 20 internal functions, the most frequently used being:

  • error_message – invoked from 8 locations to produce consistent validation feedback.
  • check_file_format – validates the overall markdown structure and uses error_message (5 calls).
  • check_description, check_auth, check_title – each route through error_message to report field‑specific problems.

The format validator is called by the test suite (scripts/tests/test_validate_format.py) but can also be invoked directly from the CLI (the file is executable).

When link validation runs, main → start_links_working_checker → check_if_list_of_links_are_working → check_if_link_is_working triggers a real network request via requests.get (the only outbound call). This path is the sole external side‑effect and lives entirely in scripts/validate/links.py.

No circular imports appear; the internal import graph consists of six modules with zero edges, meaning each file can be edited in isolation without worrying about hidden dependency loops. The functions with the widest blast radius are error_message (8 callers) and check_file_format (5 callers); changes to those will affect most validation flows.

How To Use It

# Clone the repository
git clone https://github.com/moses-y/public-apis.git
cd public-apis

# Install the Python dependencies listed for the scripts
python -m pip install -r scripts/requirements.txt

The repo does not contain a dedicated CLI entry point, but the validation can be run by executing the format module directly:

python scripts/validate/format.py path/to/README.md

Replace path/to/README.md with the markdown file you want to check (the root README.md is the default target).

To run the test suite locally:

python -m unittest discover -s scripts/tests

No additional configuration files or environment variables are required; the code relies only on the standard library and requests (installed via requirements.txt).

Real‑World Use

A CI pipeline for a documentation site could invoke the validator on every pull request:

- name: Validate API list
  run: python scripts/validate/format.py README.md

If any error_message is returned, the job fails, preventing malformed entries from being merged.

Code Health & Issues

  • Medium – Least‑privilege GITHUB_TOKEN not declared (.github/workflows/test_of_push_and_pull.yml).
  • Medium – No Dependabot or Renovate configuration (.github/dependabot.yml missing).
  • Medium – No dependency‑vulnerability scan in CI (.github/workflows/ lacks such step).
  • Medium – Checkout step keeps token persisted (.github/workflows/test_of_push_and_pull.yml).
  • Low – Jobs lack timeout-minutes (.github/workflows/test_of_push_and_pull.yml).

Additional observations: the repository ships a license (LICENSE) and a contributing guide, but it does not include a lockfile for the Python dependencies, which makes reproducible builds harder. Tests exist and GitHub Actions run them, satisfying basic CI coverage.

The Bottom Line

The repo provides a lightweight, well‑tested validator for the public‑API markdown catalog, with clear separation between format checks and live link verification. Its simplicity is a strength, but the lack of a dependency lockfile and missing security‑focused CI steps limit readiness for production‑grade automation. Teams that need a quick way to keep an API list tidy can adopt it, provided they add a lockfile and augment the CI with vulnerability scanning.