Class OparlClient

The bodies (Körperschaften) of a System — usually one per municipality.

Known OParl endpoints: the public registry at dev.oparl.org merged with the curated list (source "all", the default), or either one alone. The registry is a snapshot that is rarely updated; the live checks shipped with this package decide what an entry reports (working, checked, problem, replacedBy, note and the System data). Curated entries follow the registry's. A System listed twice appears once — under the registry's entry where both lists hold it, reporting whichever of the two live checks is newer. source "curated" makes no request.

search, oparlVersion and working filter the merged list (see EndpointFilters and filterEndpoints). A blank search or an unusable oparlVersion is rejected with an OparlValidationError before any request.

A registry that cannot be read is an error here; endpointsReport answers from the curated list instead and says why.

As endpoints, but with source "all" a registry that cannot be read (an HTTP error, a page that is not the registry, a network failure — any OparlError but an OparlValidationError) does not fail the call: entries then holds the curated list alone (filtered alike) and registryError the error. The curated list ships with the package and needs no request, so one unreachable third-party host does not take down the entry point of every workflow — but the answer is only as fresh as the release, which is why the error is handed back (the CLI logs it as a WARN record). With source "registry" the error is thrown, since there would be nothing left to return.

Fetch one OParl object by URL. The OParl filters the URL carries (created_since, created_until, modified_since, modified_until, limit, omit_internal) are set again on every redirect target, so a page URL taken from a walk's next keeps its filters even when the server moves it. Rejects non-objects and OParl/vendor error objects ({ "type": ".../Error", "message": "…" }, { "error": "…" }) with an OparlParseError.

Walk one of a Body's object lists (meetings, papers, persons, …). Filters are passed to the server as OParl query parameters; servers are required to support the date filters, but in practice some ignore them.

A Body without a legislativeTermList URL (every OParl 1.0 body) embeds its terms in legislativeTerm; those are returned as they are (pages: 0, nothing fetched), with the date filters applied locally. A term the server left without the mandatory created/modified cannot be excluded by a date filter, so it is kept and the result's note says how many terms the filter could not be applied to.

Fetch one list page and check it has a data array of objects. Without a query, the OParl filters the URL carries are set again on every redirect target (as for get). A server that answers a list URL with a bare JSON array instead of a list page (seen on an SD.NET RIM build in Essen) is read as a single page holding those objects.

Fetch a System, the entry point of an OParl server.

Walk a list from its first page along links.next, staying on the same host. maxPages 0 fetches every page. The query (filters) is set on every page, including on the server's next links (see carryQuery), on every redirect target of every page, and on the next returned — the server's own (possibly stale) values for those parameters are replaced, never sent.

Objects are listed once per id; when a page repeats an id, the later copy wins, since that is the newer one — a list that changes while it is being walked serves the edited object, or the spec's deleted: true tombstone, on the later page.

The walk gives up early — looped: true plus a note saying why — when the server's next points back at a page already fetched, or when MAX_UNPRODUCTIVE_PAGES pages in a row add no object that wasn't already listed (some servers serve the same page, or an empty one, under ever-new ?page=n links). After unproductive pages the next of the last page fetched is still returned, so the walk can be resumed by hand; after a next leading back to a fetched page it is null, as following it would only go round the loop again. A next this client refuses to follow (another host, not http), or a redirect it refuses on a later page, also ends the walk with a note, keeping the pages already fetched.

Any other failure on page 2 or later (an HTTP error, a timeout, a page that is not a list) is thrown as it is, but carries the walk so far in err.partial: the objects of the pages fetched before it, and next set to the page that failed, so the walk can be resumed there.