Passage API Requirements

Implications for API operations:

• query for an editions or manifestations (e.g.) of a work that contain the specified passage or passage range and where the result is a set
• retrieve metadata about a passage
• query for a passage based upon metadata
• given an identifier, retrieve an ordered list of passage identifiers which are children of that identifier
  • with options to retrieve
    • descendants down to a specific depth
    • ancestors up to a specific depth
    • the lowest level of each
• given an identifier retrieve the passage content plus the identifier for the next sibling:
  • within the same parent
  • within the next parent
  • with option to not retrieve content
• given an identifier retrieve the passage content plus the identifier for the next passage of the same type (if we have a notion of passage types)
  • with option to not retrieve content
• given an identifier retrieve the passage content plus the identifier for the previous sibling:
  • within the same parent
  • within the previous parent
  • with option to not retrieve content
• given an identifier retrieve the identifier for the previous passage of the same type (if we have a notion of passage types)
  • with option to not retrieve content

User Stories and Use Cases these requirements are drawn from:

• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L7
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L9
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L15
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L16

Use Cases and User Stories still to distill:

• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L31
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L32
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L33
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L34
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L35
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L40
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L41
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L42
• https://github.com/distributed-text-services/API/issues/6
• https://github.com/distributed-text-services/API/issues/24
• https://github.com/distributed-text-services/API/issues/26
• https://github.com/distributed-text-services/API/issues/27
• https://github.com/distributed-text-services/API/issues/34

And potentially:

• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L26
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L28
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L30
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L46

And possibly enabled by a passage API, but not a requirement of it specifically

• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L43
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L44
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L45
• https://github.com/distributed-text-services/API/blob/master/userstories.csv#L47
• https://github.com/distributed-text-services/API/issues/3
• https://github.com/distributed-text-services/API/issues/4

Some requirements which aren't explicitly called out in the above, but which we know are there:

• describe and navigate a "canonical" hierarchy of passages within a text that have meaning across different instantiations of that text (i.e the Hom, Il, 1.1 problem)
• describe and navigate multiple hierarchies of passages within a text (i.e. the stephanous page question)