I was evaluating Indonesian Hadith APIs and open datasets for structured application access. One API was operational: endpoints responded, JSON parsed, and records could be retrieved by number. The problem appeared when I compared those records with commonly referenced sources. Many numbers did not identify the content I expected.
The API implementation could be correct while the data assumption underneath it was wrong. That turned the work from an endpoint project into a data-provenance investigation.
This article is about software and data engineering. It does not make religious rulings or claim that any dataset is authoritative.
Availability is not reliability
API monitoring usually asks whether an endpoint responds, returns valid JSON, and meets its schema. Those checks are necessary, but they cannot prove that a record’s number, attribution, or text matches an intended publication.
In this case, a successful request proved that the application could find row N. It did not prove that row N corresponded to the same Hadith in another dataset, printed edition, or public reference.
The distinction is important:
| Layer | A successful check proves |
|---|---|
| HTTP | The service accepted and answered a request. |
| JSON/schema | The response has the expected structure and types. |
| Database lookup | The requested key maps to a stored record. |
| Source validation | The stored record corresponds to a declared source and numbering scheme. |
Only the last check addresses the mismatch I encountered.
Numbering is source metadata
I had initially treated a Hadith number as if it were a universal identifier. The comparison showed why that is unsafe. Numbering can vary with collection structure, edition, publication, translation, dataset assembly, or decisions about how records are split and grouped.
A bare integer therefore carries less information than it appears to. 123 is meaningful only together with a collection and a declared source or numbering scheme. Even then, cross-source equivalence may require validation rather than assumption.
This is a general data-engineering pattern. Page numbers, catalog identifiers, geographic names, and legal section numbers can all look stable while depending on a specific edition or authority.
How I evaluated the datasets
I started by validating the mechanics: repository contents, JSON structure, required fields, endpoint behavior, and obvious missing records. I then sampled records across more than one part of a collection instead of validating only the beginning.
For each comparison, I needed to record:
- the dataset and repository version;
- the collection name used by that source;
- the record number reported by the API;
- the text or stable excerpt used for comparison;
- the external publication or dataset being compared;
- the type of mismatch observed.
The mismatch type matters. A shifted sequence suggests a different splitting or omitted record. Isolated differences may point to transcription or mapping errors. Large sections using another scheme may be internally consistent but incompatible with the expected reference.
I also evaluated alternative open datasets rather than patching the first one immediately. A correction made without source evidence can replace one undocumented assumption with another.
The API contract had to include provenance
If source numbering differs, an API should not present number as context-free truth. A stronger record model can keep the source identity next to the source-specific number.
A conceptual response might include:
{
"collection": "<collection-identifier>",
"source": "<declared-dataset-or-edition>",
"source_number": "<source-specific-number>",
"text": "<content>",
"provenance": {
"dataset_version": "<version-or-commit>",
"notes": "<known-numbering-scheme>"
}
}These are placeholders, not a claim about a final canonical schema. The point is that provenance should travel with the data rather than live only in a README that API consumers may never see.
An internal record ID can remain stable for database relationships, but it should not be confused with a source’s published numbering. Crosswalk tables can map identifiers between sources when that mapping has been reviewed. Where no verified mapping exists, the API should say so.
Validation beyond spot checks
Manual comparison revealed the issue, but a maintainable dataset needs repeatable checks.
Structural validation can detect duplicate identifiers, missing required fields, sequence gaps, or invalid JSON. Content hashes can reveal unexpected changes between repository versions. A curated set of verified reference records can serve as regression fixtures for known positions in each collection.
Those checks still do not make the dataset authoritative. They make its behavior visible. Source review remains necessary when the question is whether a number aligns with a particular publication.
I would also keep ingestion separate from serving. The import process should preserve raw source metadata and produce a validation report. The API should expose only the dataset version that passed the selected checks, while retaining known limitations.
Repository migration did not solve data quality
Part of the work involved migrating a Git repository and deploying or consuming the API. Version control made changes traceable, but moving code and data to a new repository could not establish correctness on its own.
A clean deployment can faithfully serve an unreliable dataset. CI can verify schema and endpoints while every number remains consistently wrong relative to the expected source. The pipeline needs data-quality gates in addition to software tests.
What I learned
The operational API was only the outer layer. The core engineering problem was the meaning and provenance of the records it served.
I no longer treat a source number as a universal ID, and I would not label the resulting API authoritative without the necessary source verification. A more honest system identifies its dataset, preserves version and numbering metadata, documents mismatches, and makes comparison possible.
API availability tells me that software is running. Data reliability requires a different body of evidence.