RESTful URI Structure

Overview

There are a few kinds of passage queries that might be made:

1. Get a single passage, e.g. passage/ESV.2001:Exod.1.2
2. Get multiple passages in the same work, e.g. passage/ESV.2001:Gen.3.1;Exod.1.2
3. Get multiple passages in multiple works (including links between any linked tokens), e.g. passage/ESV.2001:Exod.1.2;KJV.1611:Exod.1
4. Get the same passage in multiple works (with links between them), e.g. passage/ESV.2001:Gen.3.1|KJV.1611
5. Get a passage from one work using the reference system of another, e.g. passage/KJV.1611:Gen.3.1/ESV.2001
6. Performing a forgiving passage lookup suitable for human input, e.g. passage?q=John+3:16+ESV; redirects to canonical URL for resource.
7. Addressing the structures and tokens that existing in a work
8. Searching

Example Queries

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" /> …

passage/KJV:Exod.1/ESV.2001

passage/ESV.2001|KJV:Exod.1

Two ideas for looking up a passage in the ESV that corresponds to Exodus 1 KJV.

passage?q=John+3:16+ESV

passage/ESV?q=John+3:16

A passage lookup which implements the same forgiveness as the ESV API. This query could do a 301 redirect to /api/rest/passage/ESV.2001:John.3.16 or return 300 Multiple Choices. The second example scopes the results to the ESV.

passage?q=John

passage?q=John&type=reference

passage?q=John&type=keyword

First is disambiguating search; the first could return either the book of John, or the instances of the name “John”. Adding the type parameter would make it explicit which kind of search you are performing. reference would return the first, and keyword would return the latter.

passage/LXX;ESV?q=God

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

passage/LXX|ESV?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)

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 data, source_url, parsings, links to other tokens, structures that contain the token (e.g. paragraphs, quotes, verses), the osisID using other works’ reference systems. Note: the actual data may not be included in the response if the work isn’t openly licensed.

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?)

work/ESV.2001/structure/12

The 12th structure (verse, paragraph, quote, etc) in the ESV. As with tokens, structures are identified by position. This resource would contain all information about the structure, such as the tokens it contains, its related structures (inside, outside, overlapping), etc

work/ESV.2001/structures

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

work/ESV.2001/structures/10-12

Atom feed of entries for each structure in the range specified.

passage/ESV.2001:Gen.1.1

work/ESV.2001/structure/3

These could refer to the same structure

Query Parameters

hierarchy	“bsp”, “bcv”, “standoff”, “milestone”, or ~?structType(,~?structType)*	Indicate which hierarchy should be primary, book-section-paragraph or book-chapter-verse; when outputting OSIS, milestone elements will be employed. list of structure types optionally prefixed by tilde to indicate milestone required.
output	xml, osis, xhtml, etc	The content type of the response.
q		Freeform search query for either a passage reference or a keyword lookup; the specific type can be indicated by supplying the type parameter; if reference then does reference resolution, if keyword then it does a word search.
fields	XPathy expressions	Instead of listing out which elements should be returned in a response, Google’s GData Partial Responses could be employed; this would only really work with XML output; it doesn’t seem to be able to list fields for omission. Does this work? …/feed?fields=*[.!=id] or maybe this could work? …/feed?fields=-id
token-markup	none, words, all	Whether or individual tokens will be marked up and output with IDs. Immensely increases response size. Would be replaced by fields parameter.
token-ids	false, true	Whether or individual tokens will include their IDs. Implies token-markup=true Would be replaced by fields parameter.
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 Would be replaced by fields parameter.
notes	all, none, or any of the types defined by OSIS	Whether or not (foot)notes should be included in the output. Would be replaced by fields parameter.

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?)
• Write grammar for URI space and Django URLConf. Antler?
• Iron out what the actual response bodies will be
• How do you address parsings and TokenMeta directly?
• Work ID resolution when multiple choices: ESV could refer to ESV.2001 or ESV.2007. Default could be latest edition; should be overridable. Alternatively, we could always return 300 Multiple Choices when this ambiguity happens.
• The GData protocol has introduced partial responses; by means of the fields query parameter which accepts a comma-separated list of XPathish expressions: https://developers.google.com/gdata/docs/2.0/reference#PartialResponse