Crossref
https://api.crossref.org/works?rows=1
DocumentationIn-depth practical guides
Define the request, check pagination, distinguish errors from absence and preserve the raw response before transformation.
Updated :

AI-generated illustration
An API returns a response to a request using a schema at a particular time. This does not mean the whole database was requested or that data stayed unchanged between calls. Retain selection, technical states and received data separately from analysis.
Read official documentation for version, scope, terms, authentication and volume limits. For an entire database, look for an official bulk export; search APIs can cap coverage.
Record endpoint, method, parameters, filters and sorting. Prefer stable identifiers to ambiguous names. Never publish keys or tokens in request logs.
Record HTTP status, reception time, format and errors. Check fields and units. HTTP 200 may still contain empty data, business errors or a changed schema.
Check announced totals and page or cursor mechanics. Count rows and unique identifiers, record duplicates and the stopping condition. Changing data can affect successive pages.
Keep raw responses and their digests. Document cleaning, filtering and conversion; link outputs to the original extract. Do not publish personal data or secrets in public logs.
Respect retry guidance for HTTP 429 or unavailable services instead of unlimited retries. A fresh extract is a new observation: compare schema, parameters and scope too.
These addresses illustrate syntax; check availability, authentication and terms in the documentation.
Reading workshop
The DEMO HTTP exchanges are fictional. This section contacts no server and performs no retries.
Fictional data and records for learning: none of these results comes from a live service query.
The scenario client retains a representation for area=A with its ETag. The fictional retry policy caps attempts at two. It guarantees no service availability.
Open each proposition to compare its diagnosis. More checks may still be needed.
No. This scenario still uses the copy of the same selection. An absent body does not become an empty table.
No. That silently changes observation scope. Parameters belong in the record.
Yes. The log must identify data used and attempts that supplied no new extraction.
Selection: GET /demo?area=A Copy: body retained; ETag="demo-v1" Condition: If-None-Match="demo-v1" Response: 304; reference to A copy Other attempt: 429; Retry-After=15 seconds DEMO policy: two attempts maximum, then stop Republication rights: check separately
The two-attempt cap belongs to this example, not the RFCs. Without a usable copy, do not invent content; plan another retrieval under the service policy.
A populated file may cover only part of the selection. Inspect totals, page size and next cursor before publishing a count.
Keep null, missing fields, empty arrays and zero distinct. Conversion can change averages or rankings.
Eurostat documents a database holding the latest dataset versions. Retain dated extracts to reproduce earlier calculations.
Worked exercise
Fictional example: the values and documents teach the method and do not describe a real organisation.
This fictional API’s contract requires success=true before processing. Check the HTTP response, application state and presence of results separately.
If the table exceeds the screen, scroll horizontally; arrow keys work when the region is focused.
| Item | Observed information |
|---|---|
| HTTP status | 200 |
| Application indicator | success=false |
| Message received | Message: quota reached |
| Results array | No array supplied |
Transport responded, but collection failed under this contract. No zero count is established. Mark extraction failed and follow the documented retry rule; do not manufacture an empty table to continue calculation.
If a successful response truly has an empty array, zero can be established for the stated query and scope. Replay with success=true but a JSON body truncated before completion: status and flag still do not suffice. Reject the incomplete batch, retain the recovery point and verify that no partial value replaced the last validated extract.
Keep a secret-redacted query, status, error, contract and retry state.
Documentation reference : IETF — RFC 9110, 200 OK · Consulted on
DOCUMENTED REFERENCE
Truthy is a technical projection. For one entity-property pair, preferred statements exclude normal ones from that projection; otherwise normal statements are selected. This is neither automatic source voting nor latest-date selection.
| Reference | Value or form | What it identifies |
|---|---|---|
| PreferredRank | Preferred | All preferred statements are selected when present for that entity and property. Preferred does not ensure uniqueness. |
| NormalRank | Normal | Normal statements are selected only if that pair has no preferred statements. Several normal values may be legitimate. |
| DeprecatedRank | Deprecated | Deprecated statements are excluded from truthy, but can remain in full statements to document errors or rejected values. |
| wdt: | Best non-deprecated rank | The direct path uses best non-deprecated ranks without qualifiers. Extracted values are not automatically current, complete or supported. |
| wikibase:BestRank | Full statement selection | This type selects best-rank full statement nodes, retaining access to qualifiers and references. |
| Scope | Entity + property | The rule is per entity and property. Preferred population does not select a foundation date, name or another property. |
If all statements are deprecated, do not invent a fallback to them. For disagreement or history read full statements and retain ranks. Missing direct-query values may be filtered by rank rather than absent from the database.
No. Rank and temporal qualifiers are separate mechanisms. Check point in time and rank practice before calling it latest; multiple preferred statements may coexist.
Documentation consulted on .
DOCUMENTED REFERENCE
A JSON response contains more than a value. The real excerpt below concerns Finnish density in 2023. Its header reports a WDI update on 8 October 2026; this snapshot was retrieved on 23 October. Those three dates answer different questions.
| Reference | Value or form | What it identifies |
|---|---|---|
| date | 2023 | Observation year. It does not become 2026 because the request ran in 2026. |
| lastupdated | 2026-10-08 | Update date reported in the source header. It does not by itself certify revision of this particular value. |
| extracted | 2026-10-23 | Date this local snapshot was assembled; it replaces neither the observation period nor the source date. |
| unit | "" | The record has an empty unit field. The EN.POP.DNST definition still specifies people per km² of land: empty does not mean dimensionless. |
| decimal / value | 0 / 18.3705454665088 | The decimal field is zero while value has fractional digits. Preserve the supplied value; do not interpret this field as an error margin. |
| pages / total | 1 / 4 | The four observations fit on one response page. Another request may be paginated: check pages and total before treating collection as complete. |
https://api.worldbank.org/v2/country/FRA;DEU;ESP;FIN/indicator/EN.POP.DNST?date=2023&format=json&per_page=100
[
{
"page": 1,
"pages": 1,
"per_page": 100,
"total": 4,
"sourceid": "2",
"lastupdated": "2026-10-08"
},
[
{
"indicator": {
"id": "EN.POP.DNST",
"value": "Population density (people per sq. km of land area)"
},
"country": {
"id": "FI",
"value": "Finland"
},
"countryiso3code": "FIN",
"date": "2023",
"value": 18.3705454665088,
"unit": "",
"obs_status": "",
"decimal": 0
}
]
]This is a dated API snapshot, without automatic refresh on page load. A shared country code does not prove identical territorial coverage across series. To reproduce the analysis, retain the full request, definitions and missing values; do not turn null into zero.
Documentation consulted on .
DOCUMENTED REFERENCE
A parameter list is an ordered sequence of name-value pairs. The same name may occur twice. This tool applies application/x-www-form-urlencoded through URLSearchParams to two single-line values, then parses the result; it submits no form.
| Reference | Value or form | What it identifies |
|---|---|---|
| U+0020 | + | A U+0020 space is serialized as + in this format. This is not a universal rule for every URL component. |
| + | %2B | A plus sign belonging to the value becomes %2B. Pasting C++ directly into an already encoded string would make its two plus signs parse as spaces. |
| & | %26 | An ampersand within a value becomes %26, so it does not introduce an extra parameter. |
| = | %3D | An equals sign within a value becomes %3D; the structural name-value separator remains =. |
| été | %C3%A9t%C3%A9 | Non-ASCII characters are encoded from UTF-8. Percent escapes represent bytes, not a count of displayed letters. |
| append / get / getAll / set | ordered pairs | append retains a new occurrence. get returns the first value; getAll returns all values in order. set replaces the first and removes the other occurrences of that name. |
Two demonstration values calculated on this page.
Two pairs preserved in order.
tag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9
["C++ & IA","été"]
"C++ & IA"
Encoding is neither encryption nor HTML sanitization. This demonstration does not simulate form-control selection, multipart files or form line-break normalization. The server must explicitly define duplicate-parameter handling; converting the list to an object too early can lose values.
Documentation consulted on .
No. Inspect body, filters, totals and pagination.
No. Choose the useful scope and document its limits.
It compares preserved file bytes. Methods and data quality require their own checks.
Keep the last step confirmed, parameters and continuation references. The recovery should check the duplications and possible changes of the data rather than suppose a simple addition of answers.
DOCUMENTED REFERENCE
Two editors may read one version and submit different corrections. A precondition lets the server reject a write based on an older representation. These examples are fictional: v1 and v2 are teaching tags, not observations from a service.
Read → concurrent edit → rejected write: fictional example.
| Reference | Value or form | What it identifies |
|---|---|---|
| PUT · If-Match: "v1" | ETag: "v2" → 412 | The document changed after it was read. Strong comparison fails for this PUT: do not replace the current version. Read it again and review the differences. |
| PUT · If-Match: "v2" | ETag: "v2" → ✓ | The strong tags match, so this precondition permits normal processing to continue. It guarantees neither status 200 nor success of other checks. |
| PUT · If-Match: W/"v2" | ETag: "v2" → 412 | The opaque text matches but one tag is weak. If-Match requires strong comparison and fails. Removing W/ on the client does not create a strong validator. |
| PUT · If-None-Match: * | Present → 412 / Absent → ✓ | For a write, the asterisk requires that no current representation exist. An existing representation makes the condition fail; absence permits processing to continue. |
| GET · If-None-Match: W/"v2" | ETag: "v2" → 304 | For GET or HEAD, If-None-Match uses weak comparison. A match leads to 304: reuse the retained copy without a new response body. |
| 428 | Precondition Required | The server requires a conditional request. A missing precondition differs from 412, where a supplied condition was false. A 428 response must not be cached. |
Change the method, state and condition. Enter a quoted tag, a comma-separated tag list or * alone. Evaluation stays in your browser. With * or an absent representation, the current ETag is not used.
412: precondition false. Do not perform the requested operation.
Local teaching simulation: no API request is sent and no data is saved.
Condition satisfied: continue the other checks and normal processing. No success status is inferred.412: precondition false. Do not perform the requested operation.304: precondition false for GET/HEAD. Reuse the retained copy.Invalid syntax: use quoted HTTP tags or * alone. The current ETag must be one tag when a representation exists.This exercise evaluates one precondition for one resource before acting. It assumes an otherwise acceptable request and excludes the special case of an operation already completed successfully. Authentication, authorization, document validation and business rules still apply. An API must check and apply the change atomically to prevent lost updates.
Documentation consulted on .
DEEPER READING / PRACTICE
A API provides useful data, but the result depends on settings and pageing. The collection must keep the complete request and the conditions necessary to understand the answer.
Updated on .
Release URL, parameters, status, format and page. Control the filters, volume limits and returned errors without exposing secrets in the journal.
A successful answer may contain only one page of results. Repeating the request later may provide a different state if the data has changed.
The collection journal combines request, date, preserved answer, coverage and limit. It specifies how to recover or check the extraction.