正文
获取原文件references/api_contracts.md
Reviewed 2026-09-30 against official documentation. The bundled clients use read-only requests; no registration, account mutation, or full-text bulk harvesting is part of this skill.
| Service | Request and authentication | Response and paging |
|---|---|---|
| OpenAlex | GET https://api.openalex.org/works; search, optional filter and sort=cited_by_count:desc; optional Authorization: Bearer from OPENALEX_API_KEY. Keyless casual use is supported. mailto is a contact identifier, not a quota upgrade. |
results[] and meta.next_cursor. Start cursor=*, follow returned cursors; supported per_page maximum is 100 (per-page is accepted). Stop at the requested limit or terminal cursor. Any failed page aborts the export. |
| PubMed search | GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi; db=pubmed, term, retmax, retmode=json, tool, optional email and api_key. |
esearchresult.count and idlist. Only the first 10,000 matches are accessible; retstart cannot bypass this ceiling. The bundled command caps the request and reports that limit. |
| PubMed records | GET .../efetch.fcgi; db=pubmed, comma-separated id, retmode=xml, same caller parameters. |
PubmedArticleSet/PubmedArticle; the client batches 200 IDs and verifies that all requested IDs were parsed. PubmedBookArticle is not implemented and produces an explicit incomplete-retrieval failure. |
| PMC conversion | GET https://pmc.ncbi.nlm.nih.gov/tools/idconv/api/v1/articles/; ids, format=json, tool, optional email. No NCBI API key is sent here. |
records[] maps PMID/PMCID/DOI only for PMC-held articles. pmid may be numeric. This helper sends one ID; the service accepts 200 same-type IDs per request, without paging. The ID converter remains distinct from the retired OA download service. |
| Crossref | GET https://api.crossref.org/works/{encoded-doi}; public metadata needs no key. |
Singleton JSON message; author/title/container/date fields can be incomplete. Extract the publication date, not created, deposited, or indexed. No pagination. Public single-record limit is 5/s; list requests are 1/s. Polite equivalents are 10/s and 3/s; respect response headers. |
| DataCite | GET https://api.datacite.org/dois/{encoded-doi}; public findable records need no credentials. |
Singleton data.id and data.attributes, not Crossref's schema. Used by the DOI validator after Crossref 404. The general metadata extractor currently has no DataCite mapper; use DOI-to-BibTeX conversion instead. |
| DOI negotiation | GET https://doi.org/{encoded-doi} with Accept: application/x-bibtex; redirects are followed to the registration agency. No key. |
One BibTeX record; the converter rejects non-BibTeX responses and generates its shared citation key. No pagination. Supports participating agencies beyond Crossref. |
| DOI resolver validation | Same DOI URL, GET without following redirects after both Crossref and DataCite lack a record. | A redirect with a Location confirms registration; 404 indicates missing DOI. Timeouts, throttling, malformed responses, or other statuses remain inconclusive warnings, never a successful verification. Publisher accessibility and bibliographic identity still need manual review. |
| arXiv | GET https://export.arxiv.org/api/query; id_list, max_results=1; no key. One connection, at most one request per three seconds across all workers. |
Atom feed with optional DOI/journal reference. Reject API error entries; preserve requested vN versions. Single-ID lookup has no paging. A DOI alone does not prove journal publication. |
PubMed's ESummary (esummary.fcgi, retmode=json) returns result.uids and
UID-keyed records. ELink (elink.fcgi, cmd=neighbor) returns link sets;
pubmed_pmc requires target db=pmc, whereas related/cited-in PubMed links use
db=pubmed. EInfo (einfo.fcgi) describes database fields and links. These
manual alternatives in the PubMed reference are illustrative, not used by the
bundled client. NCBI E-utilities limits are 3 requests/s without a key or 10/s
with a key; account for other processes sharing the same IP/key.
Google Scholar has no supported bulk API. scholarly.search_pubs is an unofficial
iterator with year_low/year_high; --sort-by citations only sorts the returned
sample. Google caps displayed results at 1,000 per query. Follow robots.txt and
stop on blocking. Proxy support is optional and was not exercised.
Verification evidence and limits
Credential-free read-only smoke checks on 2026-09-30 returned HTTP 200 and the expected parsed shapes for PMC conversion (PMC7611378 returned numeric PMID 27102758), ESearch/EFetch (PMID 34265844), Crossref and DOI BibTeX negotiation (10.1038/s41586-021-03819-2), DataCite (10.14454/qdd3-ps68), arXiv (1706.03762 returned the v7 Atom entry), and OpenAlex (one work plus cursor). These checks confirm those responses at that time, not uptime or bulk coverage.
Regression tests mock pagination failures, missing PubMed batches, arXiv error feeds/pacing, DOI transport failures, numeric PMC IDs, and CLI input contracts. Authenticated quota handling, Scholar/proxies, arbitrary publisher-page metadata, Zotero exports, and all illustrative search queries were not exercised live.
Official sources
- OpenAlex authentication, pagination, and search.
- NCBI E-utilities reference, NLM API parameter guide, and PubMed result-window change.
- PMC ID Converter API.
- Crossref REST API, current rate-limit distinction, and content negotiation.
- DataCite public API and singleton schema.
- arXiv API manual and usage limits.
- Google Scholar Help and scholarly API.
- Pyzotero export types and pagination.