URL Parameters

Scalar API queries are grouped into four scopes. Each scope allows access to a different piece of a Scalar book. A combination of calls might be needed to gain all information about a Scalar book (e.g., the book’s title and all of its content). However, a single call, for example to instancesof/content, will return all content in a Scalar book. Adding one or more GET variables to the same call will return additional information, for example, all content plus all relationships between content which effectively models the entire Scalar book in a single query.

Install
Information about a Scalar installation including its title and list of public Scalar books.
URL structure: http://domain/install/rdf
Example: http://scalar.usc.edu/works/rdf

Book
Information about a Scalar book including its title, authors, and table of contents.
URL structure: http://domain/install/book/rdf
Example: http://scalar.usc.edu/works/guide/rdf

Instances Of
A list of nodes by a certain type (class), such as all nodes (content), text-based nodes (pages), or paths. Supported classes are content, page, media, path, tag, annotation, reply, and reference.
URL structure: http://domain/install/book/rdf/instancesof/class
Examples:
http://scalar.usc.edu/works/guide/rdf/instancesof/content
http://scalar.usc.edu/works/guide/rdf/instancesof/page
http://scalar.usc.edu/works/guide/rdf/instancesof/path

Node
Information about a specific node.
URL structure: http://domain/install/book/rdf/node/node-URI-segment
Example: http://scalar.usc.edu/works/guide/rdf/node/index
Or, use the file extension shortcut:
Examples:
http://scalar.usc.edu/works/guide/index.rdfxml
​http://scalar.usc.edu/works/guide/index.rdfjson

GET Variables

A series of GET variables are available to change the information that is output in RDF. Some options can be placed on queries of any scope, such as the format option. However, others can only be placed in context of certain scopes, such as versions which requires content nodes to be present.

Format
Change the RDF output format. The default is XML.
URL structure: ?format=[xml|json]
Scope: Install, Book, InstancesOf, Node
Example: http://scalar.usc.edu/works/guide/rdf/instancesof/content?format=json

JSON-P
A callback function can be inserted to support JSON-P.
URL structure: ?format=json&callback=(string)
Scope: Install, Book, InstancesOf, Node
Example: http://scalar.usc.edu/works/guide/rdf/instancesof/content?format=json&callback=abcdef

Versions
By default the most recent version of each content node is returned; to return all versions use this option. Note that this can be an expensive call which will take longer for the server to produce.
URL structure: ?versions=1
Scope: InstancesOf, Node
Example: http://scalar.usc.edu/works/guide/rdf/instancesof/content?versions=1

Relationship recursion
By default, content and version nodes will be displayed. However, relationship nodes (hasBody/hasTarget) can be added based on a “recursion level,” or, the amount of recursions through content relationships that will be returned. For example, asking for recursion 1 will return content and version nodes with their direct relationships to other content (ie, that a node is a tag, or in a path). Recursion 2 will return relationships of the nodes that are in turn related to the original nodes. Note that recursion is an expensive call that could take time for the server to produce. Generally, recursion 1 should be sufficient.
URL structure: ?rec=[#]
Scope: InstancesOf, Node
Example: http://scalar.usc.edu/works/guide/rdf/instancesof/content?rec=1

References
Many Scalar pages reference media through URLs in their text content. In the front-end, these references are visualized by the various Scalar views. In the RDF API, these relationships can be output for easy access (removing the need to text-mine the content for the same information). Additionally, each media node will describe what pages reference them (ie, the reverse information).
URL structure: ?ref=1
Scope: InstancesOf, Node
Example: http://scalar.usc.edu/works/guide/rdf/instancesof/content?ref=1

Restrict
Some recursion calls can take a long time for the server produce. Therefore, you can request that only certain relationship types are included in the query. For example, you might request that the server only return path relationships, excluding other types such as tag or annotation.
URL structure: ?res=[path|tag|annotation|reference|reply]
Scope: InstancesOf, Node
Example: http://scalar.usc.edu/works/guide/rdf/instancesof/content?res=path

Search
Searching will return nodes where certain fields (title, description, etc) match the search query.
URL structure: ?sq=(search string)
Scope: InstancesOf
Example: http://scalar.usc.edu/works/guide/rdf/instancesof/content?sq=metadata

Pagination
The number of nodes to return can be restricted using start and results fields. For example, asking for start=0, results=20 will return the first twenty nodes; start=20, results=20 will return the next twenty. Note that pagination acts on the base nodes being returned. If recursion is present (?rec=1 or greater), then more than twenty results might be returned in the example above, since the relationship nodes, and the nodes referenced in those relationships, will also be returned along with the base nodes.
URL structure: ?start=(int)&results=(int)
Scope: InstancesOf
Example: http://scalar.usc.edu/works/guide/rdf/instancesof/content?start=20&results=20

Hash Fragments

When working with relationship nodes, it is often helpful to know what type of relationship is being defined by the body/target pair. In the relationship node, this information is kept in the hash fragment of the target’s URL. The hash fragment is the string after the “#” character. Sometimes the hash fragment contains more than one field and value, in which case they will be separated by an ampersand.  Note that relationship nodes will only be displayed if the recursion level is greater than zero, set with the ?rec=1 GET variable.

Tag
A tag relationship will have no hash value.

Path
Fragment: index=(index number starting with 1)

Annotation
Time-based Annotations of audio & video
Fragment: t=npt:[decimal start seconds],[decimal end seconds]
Spatial Annotations of images
Fragment: xywh=[left][%],[top][%],[width][%],[height][%]
Line Annotations of text files
Fragment: line=[start line number],[end line number]

Comment
Fragment: datetime=(datetime)&paragraph=[number]

Reference
References to media pages from text pages will be expressed with the dcterms:references and dcterms:hasReference predicates inside each RDF node when the ?ref=1 GET variable is present.