RESTful URI Structure

Example Queries

Base URI: /api/rest/v1/

work/ESV.2001

work/KJV.1611

work/Bible.Crossway.ESV

Get the work that has shares the info specified, such as year, publisher, abbreviation; returns a list of all structures that have osisIDs? List of all books? If work identifier is ambiguous, returns response of Atom list of works response with 300 Multiple Choices status.

passage/ESV:John.1-John.2,John.4

passage/ESV:John.1;KJV:John.5

passage/ESV:John.1-John.2;KJV:John.2

First get passage only from ESV, then get part from ESV then KJV, then get some from ESV only and get rest from both ESV and KJV which will likely be parallel passages and have interlinkages.

passage/ESV:John.1-John.2,John.4|KJV

passage/NET:Exod.1|LXX,Vulgate

passage/ESV:Gen-Mal|LXX

passage/LXX|ESV

Explicit parallel passage lookups, as opposed to accidental lookup above as with ESV:John.2;KJV:John.2. The works that appear after the vertical bar will use the reference system of the references before the bar. Note that the final two examples are practically equivalent, since the LXX only has Gen-Mal. Links between tokens in parallel works will not be inline but will appear in metadata section; links will reference tokens in the response document by ID, for example:
<link hrefs="#a #b" /> <link hrefs="#c #d #e" /> …

work/ESV.2001/token/23

The 23rd token in the ESV. Position indices are the way tokens are persistently identified. This means that existing editions cannot be modified; if a change needs to be made, a whole additional work needs to be instantiated. This works for works that don’t often change, but it will not work for works that are more fluid; in that case we’d need to use a unique ID. This token resource includes all of the available information about a token, including the source_url, parsings, links to other tokens, structures that contain the token (e.g. paragraphs, quotes, verses), the osisID using other works’ reference systems.

work/ESV.2001/tokens

Atom feed of entries for each token; each entry is an abbreviated form of the token resource above. Response would obviously be paged.

work/ESV.2001/tokens/42-67

Atom feed of tokens having positions in the range provided.

work/ESV.2001/token/23

passage/ESV.2001@token(23)

passage/ESV.2001:Gen@token(23)

passage/ESV.2001@word(12) (Maybe)

These would refer to the same information. The first returns an Atom entry, the second returns OSIS, XHTML, or whatever content type is accepted. The token() grain’s position parameter refer to the token position within the associated structure if specified. That is if ESV.2001:Exod@token(23)

would refer to the 23rd token of Exodus, not the entire work. The word() grain is an idea.

work/ESV.2001/tokens/23-37

passage/ESV.2001@token(23)-ESV.2001@token(37)

passage/ESV.2001@token(23)-@token(37) (Allow redundant OSIS work to be omitted?)

search?q=God

Searching all works

work/ESV/search?q=God

Searching all ESV editions

work/LXX;ESV/search?q=God

Searching the Septuagint and the the entire text of the ESV editions

passage/LXX|ESV/search?q=God

Searching the Septuagint and the Old Testament of the ESV editions (note the use of the bar causes the ESV passages to be restricted to those that also appear in the LXX, meaning the scope is limited to OT)

Query Parameters

hierarchy	bsp, bcv	Indicate which hierarchy should be primary, book-section-paragraph or book-chapter-verse; when outputting OSIS, milestone elements will be employed; when outputting HTML, milestoned paragraphs will be represented by two line breaks.
accept	application/x-osis+xml, application/xhtml+xml, text/plain, application/atom+xml, audio/mp3 …	Output format; corresponds to Accept request header.
token-markup	none, word, all	Whether or individual tokens will be marked up and output with IDs. Immensely increases response size.
token-ids	false, true	Whether or individual tokens will include their IDs. Implies token-markup=true
token-srcs	false, true	Whether or individual tokens will include links to their source URLs. Extensive use of xml:base will be attempted. Implies token-markup=true
notes	true, false	Whether or not (foot)notes should be included in the output.

Additional parameters as found in the ESV API such as include-passage-references, include-verse-numbers, include-footnotes are always returned in the output since they add minimal overhead and can be easily removed/hidden via stylesheets. This API defaults to including all information; the only parameters that exist are for options that will significantly affect the response size.

TODO

• Plain text format accounts for 60% of queries to ESV API; HTML and XML both have only 20% each. Plain text needs to be a full content type (maybe an XSLT stylesheet can generate it automatically?)