Community Services Journal Annotations Service V1.3

Overview

The Annotations service allows developers on any platform to securely create, update, retrieve and delete annotations of any content in the Gospel Library and other conforming data stores.

Church applications being written for various mobile platforms as well as LDS.org will allow users to annotate content. These annotations include the ability to:

Highlight verses and paragraphs or portions of verses and paragraphs using color and typographic conventions like underlining.
Add user-defined tags to highlighted elements.
Add cross-references to highlighted elements.
Add brief comments or notes to highlighted elements.
Share one’s annotations with others in one’s trust network, i.e., family, ward, stake, etc (future).
Include official annotations, like Scripture Mastery or Preach My Gospel, with one’s own annotations (future).
Synchronize annotations made on one platform with those made on any other platform.

Technical Overview

The Annotation/Journal service uses a MarkLogic XML database. It serves the purpose of storing data that adheres to pre-defined XML schemas, including, the Annotation schema and the Folders schema. These schemas provides several tags to assist you in providing semantic clarity to the content that you are storing. The list of other schemas and history changes can be found here.

The Annotation service uses an SSO environment referred to as WAM to provide authentication. Information about this service can be found here. The Annotation service uses some HTTP header information to determine the LDS Account ID of the logged-in user. The logged-in user can only see annotations they have created.

The HTTP return error response codes may include:

401 Unauthorized - For access to the service without an authenticated user

400 Bad Request - When a bad parameter or data is provided

404 Not Found - When accessing an invalid method or the resource can not be found

302 Not Found - When an invalid cookie is supplied

The following terms are used throughout this document:

annotation - The highlight, bookmark, journal, or reference created by a user.
folder - A place to group similar annotations.
content - The content on a site that the user may mark up with their annotation.

Transport Media Types

The Annotation service supports two transport media types XML and JSON. The return data type is determined by the Accept header value. If the Accept header is set to application/json then JSON will be returned otherwise XML will be returned. The Content-Type header indicates the Internet media type of the message content. If the Content-Type header is application/json then JSON is expected in the HTTP body otherwise XML is expected.

There are two important differences between XML and JSON:

First, there are no namespaces in JSON. Currently, there is no way to specify a different schema version when transporting annotations over JSON. For now, we are inferring the version from the endpoint URL.

Second, the note-content tag's value is straight HTML. This is so that you, the consumer don't have to translate a user's HTML into JSON in order to store it in the database or from JSON back into HTML to display it.

Base URL

The following is a list of base URL's for different environments:

Environment	Access	URL
Dev	Internal	http://dev.lds.org/ws/annotation/v1.3/Services/rest/
Test	Internal	http://test.lds.org/ws/annotation/v1.3/Services/rest/
Integration	Internal	http://int.lds.org/ws/annotation/v1.3/Services/rest/
Stage	Internal	http://uat.lds.org/ws/annotation/v1.3/Services/rest/
Community	External	https://tech.lds.org/ws/annotation/v1.3/Services/rest/
Production	External	http://lds.org/ws/annotation/v1.3/Services/rest/

Annotation Methods

Retrieve Annotations Using Optional Query Parameters

Retrieve the annotations for the logged-in user, keyed by various query parameters. Invoked via an http GET call with the base URL.

Method

/annotations

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/annotations?type=bookmark&since=2011-02-14T10:00:00.123-07:00 HTTP/1.1
  Accept: application/xml

Parameters

locale (optional) - The annotations’ locale

Valid values: any valid locale code

Example: locale=eng

uri (optional) - The annotations’ uri

Valid values: Any url

Example: uri=/scriptures/bofm/1-ne/3

scope (optional) - The annotations’ scope

Valid values: Any text

Example: scope=2-3

type (optional) - The type of the annotation. Can contain more than one type when delimited with comma's.

Valid values: highlight, bookmark, journal, reference

Example: type=highlight,bookmark

since (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is greater than or equal to the time stamp specified by since.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: since=2011-02-14T10:00:00.123-07:00

before (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is less than the time stamp specified by before.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: before=2011-02-14T10:00:00.123-07:00

status (optional) - The annotations’ status attribute. The default (status not specified) is to return annotations that have no status attribute value. The status values may contain more than one value when delimited with comma's.

Valid values: all, trashed, deleted

Example: status=trashed,deleted

tag (optional) - The annotations’ tag element values. The tag values may contain more than one value when delimited with comma's.

Valid values: Any tag value

Example: tag=Favorite

searchPhrase (optional) - The phrase to use for searching annotation content specified by searchFields. The search will be case and diacritic insensitive.

Valid values: Any phrase of words with spaces replaced by %20

Example: searchPhrase=love%20at%20home

searchFields (optional) - The annotation fields to search for the phrase specified in searchPhrase. The match is true is the searchPhrase is found in any of the searchFields specified. The default is to search all annotation content.

Valid values: Any combination of "tag", "note", and "name" that are comma delimited.

Example: searchFields=tag,note

facets (optional) - If true then facet information will be returned containing count information. Default is false.

Valid values: true, or false

Example: facets=true

orderDir (optional) - Specifies the sorting order of the returned annotations. The default is descending.

Valid values: ascending or descending

Example: orderDir=ascending

start (optional) - The starting position number of the annotations to return. It is used for paging. It is 1 based and the default is 1.

Valid values: 1 to the number of annotations

Example: start=10

numberToReturn (optional) - The number of annotations to return. It is used for paging. The default is to return 1000.

Valid values: 1 to the number of annotations

Example: numberToReturn=20

Returns

The annotations that fit the search criteria represented as a stream of either XML or JSON

Example XML

        <annotations total="2">
           <annotation id="1-1299103551060" scope="23-25" locale="eng" type="reference" uri="/scriptures/bofm/1-ne/1" person-id="11" status="deleted" xmlns="http://lds.org/schema/annotation">
              <highlights>
                 <highlight offset-start="24" style="red-underline" color="000000" offset-end="30" uri="/scriptures/nt/james/1.3"/>
              </highlights>
              <groups>
                 <group type="leader">Leader</group>
              </groups>
              <device>iphone</device>
              <tags>
                 <tag>love</tag>
                 <tag>love at home</tag>
              </tags>
              <refs>
                 <ref public="false" uri="/scriptures/bofm/hel/1.13">Helaman 1:13</ref>
              </refs>
              <timestamp>2011-04-07T14:10:06.289-06:00</timestamp>
           </annotation>
           <annotation id="1-1299103549931" scope="23-25" locale="eng" type="reference" uri="/scriptures/bofm/1-ne/1" person-id="11" status="deleted" xmlns="http://lds.org/schema/annotation">
              <highlights>
                 <highlight offset-start="24" style="red-underline" color="000000" offset-end="30" uri="/scriptures/nt/james/1.3"/>
              </highlights>
              <groups>
                 <group type="leader">Leader</group>
              </groups>
              <device>iphone</device>
              <tags>
                 <tag>love</tag>
                 <tag>love at home</tag>
              </tags>
              <refs>
                 <ref public="false" uri="/scriptures/bofm/hel/1.17">Helaman 1:17</ref>
              </refs>
              <timestamp>2011-04-07T14:10:06.289-06:00</timestamp>
           </annotation>
        </annotations>

Example JSON

        {"annotations": {
           "@total": "2",
           "annotation":    [
                    {
                 "@id": "1-1299103551060",
                 "@scope": "23-25",
                 "@locale": "eng",
                 "@type": "reference",
                 "@uri": "/scriptures/bofm/1-ne/1",
                 "@person-id": "11",
                 "@status": "deleted",
                 "highlights": {"highlight":          {
                    "@offset-start": "24",
                    "@style": "red-underline",
                    "@color": "000000",
                    "@offset-end": "30",
                    "@uri": "/scriptures/nt/james/1.3"
                 }},
                 "groups": {"group":          {
                    "@type": "leader",
                    "$": "Leader"
                 }},
                 "source": "http://lds.org",
                 "device": "iphone",
                 "tags": {"tag":          [
                    "love",
                    "love at home"
                 ]},
                 "refs": {"ref":          {
                    "@public": "false",
                    "@uri": "/scriptures/bofm/hel/1.13",
                    "$": "Helaman 1:13"
                 }},
                 "timestamp": "2011-04-07T14:10:06.289-06:00"
              },
                    {
                 "@id": "1-1299103549931",
                 "@scope": "23-25",
                 "@locale": "eng",
                 "@type": "reference",
                 "@uri": "/scriptures/bofm/1-ne/1",
                 "@person-id": "11",
                 "@status": "deleted",
                 "highlights": {"highlight":          {
                    "@offset-start": "24",
                    "@style": "red-underline",
                    "@color": "000000",
                    "@offset-end": "30",
                    "@uri": "/scriptures/nt/james/1.3"
                 }},
                 "groups": {"group":          {
                    "@type": "leader",
                    "$": "Leader"
                 }},
                 "source": "http://lds.org",
                 "device": "iphone",
                 "tags": {"tag":          [
                    "love",
                    "love at home"
                 ]},
                 "refs": {"ref":          {
                    "@public": "false",
                    "@uri": "/scriptures/bofm/hel/1.17",
                    "$": "Helaman 1:17"
                 }},
                 "timestamp": "2011-04-07T14:10:06.289-06:00"
              }
           ]
        }}

Retrieve Annotations By Id

Retrieve a specific annotation by its identifier. Note: Annotation Id's are specific to the user.

Method

/annotation/{annotationId}

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/annotation/314159 HTTP/1.1
  Accept: application/json

Parameters

annotationId (required) - The annotation’s identifier

Valid values: Any text

Example: 314159

Returns

The annotation represented as a stream of either XML or JSON

Retrieve Annotations By Folder Id

Retrieve the annotations that belong to a folder.

Method

/folders/{folderId}/annotations

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/folders/1/annotations HTTP/1.1
  Accept: application/xml

Parameters

folderId (required) - The folder's identifier (guid).

Valid values: Any text

Example: 1

locale (optional) - The annotations’ locale

Valid values: any valid locale code

Example: locale=eng

uri (optional) - The annotations’ uri

Valid values: Any url

Example: uri=/scriptures/bofm/1-ne/3

scope (optional) - The annotations’ scope

Valid values: Any text

Example: scope=2-3

type (optional) - The type of the annotation. Can contain more than one type when delimited with comma's.

Valid values: highlight, bookmark, journal, reference

Example: type=highlight,bookmark

since (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is greater than or equal to the time stamp specified by since.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: since=2011-02-14T10:00:00.123-07:00

before (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is less than the time stamp specified by before.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: before=2011-02-14T10:00:00.123-07:00

status (optional) - The annotations’ status attribute. The default (status not specified) is to return annotations that have no status attribute value. The status values may contain more than one value when delimited with comma's.

Valid values: all, trashed, deleted

Example: status=trashed,deleted

tag (optional) - The annotations’ tag element values. The tag values may contain more than one value when delimited with comma's.

Valid values: Any tag value

Example: tag=Favorite

searchPhrase (optional) - The phrase to use for searching annotation content specified by searchFields. The search will be case and diacritic insensitive.

Valid values: Any phrase of words with spaces replaced by %20

Example: searchPhrase=love%20at%20home

searchFields (optional) - The annotation fields to search for the phrase specified in searchPhrase. The match is true is the searchPhrase is found in any of the searchFields specified. The default is to search all annotation content.

Valid values: Any combination of "tag", "note", and "name" that are comma delimited.

Example: searchFields=tag,note

facets (optional) - If true then facet information will be returned containing count information. Default is false.

Valid values: true, or false

Example: facets=true

orderDir (optional) - Specifies the sorting order of the returned annotations. The default is descending.

Valid values: ascending or descending

Example: orderDir=ascending

start (optional) - The starting position number of the annotations to return. It is used for paging. It is 1 based and the default is 1.

Valid values: 1 to the number of annotations

Example: start=10

numberToReturn (optional) - The number of annotations to return. It is used for paging. The default is to return 1000.

Valid values: 1 to the number of annotations

Example: numberToReturn=20

Returns

The annotations in the folder represented as a stream of either XML or JSON

Example XML

        <annotations total="1">
           <annotation uri="/scriptures/bofm/1-ne/3" type="highlight" locale="eng" id="2012" person-id="11" xmlns="http://lds.org/schema/annotation">
              <highlights>
                 <highlight uri="/test/uri/para1" color="FFF8AA" offset-start="-1" offset-end="2"/>
              </highlights>
              <folders>
                 <folder uri="/study-tools/folders/11/1"/>
              </folders>
              <device>web</device>
              <tags>
                 <tag>MyTag1</tag>
                 <tag>MyTag2</tag>
              </tags>
              <timestamp>2011-01-26T01:04:00.123-06:00</timestamp>
           </annotation>
        </annotations>

Example JSON

        {"annotations": {
           "@total": "1",
           "annotation":    {
              "@uri": "/test/uri",
              "@type": "highlight",
              "@locale": "eng",
              "@id": "2012",
              "@person-id": "11",
              "highlights": {"highlight":       {
                 "@uri": "/test/uri/para1",
                 "@color": "FFF8AA",
                 "@offset-start": "-1",
                 "@offset-end": "2"
              }},
              "folders": {"folder": {"@uri": "/study-tools/folders/11/1"}},
              "device": "web",
              "tags": {"tag":       [
                 "MyTag1",
                 "MyTag2"
              ]},
              "timestamp": "2011-01-26T01:04:00.123-06:00"
           }
        }}

Retrieve Annotations Not Associated with a Folder

Retrieve the annotations that do not belong to any folder.

Method

/folders/unfiled-annotations

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/folders/unfiled-annotations HTTP/1.1
  Accept: application/xml

Parameters

locale (optional) - The annotations’ locale

Valid values: any valid locale code

Example: locale=eng

uri (optional) - The annotations’ uri

Valid values: Any url

Example: uri=/scriptures/bofm/1-ne/3

scope (optional) - The annotations’ scope

Valid values: Any text

Example: scope=2-3

type (optional) - The type of the annotation. Can contain more than one type when delimited with comma's.

Valid values: highlight, bookmark, journal, reference

Example: type=highlight,bookmark

since (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is greater than or equal to the time stamp specified by since.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: since=2011-02-14T10:00:00.123-07:00

before (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is less than the time stamp specified by before.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: before=2011-02-14T10:00:00.123-07:00

status (optional) - The annotations’ status attribute. The default (status not specified) is to return annotations that have no status attribute value. The status values may contain more than one value when delimited with comma's.

Valid values: all, trashed, deleted

Example: status=trashed,deleted

tag (optional) - The annotations’ tag element values. The tag values may contain more than one value when delimited with comma's.

Valid values: Any tag value

Example: tag=Favorite

searchPhrase (optional) - The phrase to use for searching annotation content specified by searchFields. The search will be case and diacritic insensitive.

Valid values: Any phrase of words with spaces replaced by %20

Example: searchPhrase=love%20at%20home

searchFields (optional) - The annotation fields to search for the phrase specified in searchPhrase. The match is true is the searchPhrase is found in any of the searchFields specified. The default is to search all annotation content.

Valid values: Any combination of "tag", "note", and "name" that are comma delimited.

Example: searchFields=tag,note

facets (optional) - If true then facet information will be returned containing count information. Default is false.

Valid values: true, or false

Example: facets=true

orderDir (optional) - Specifies the sorting order of the returned annotations. The default is descending.

Valid values: ascending or descending

Example: orderDir=ascending

start (optional) - The starting position number of the annotations to return. It is used for paging. It is 1 based and the default is 1.

Valid values: 1 to the number of annotations

Example: start=10

numberToReturn (optional) - The number of annotations to return. It is used for paging. The default is to return 1000.

Valid values: 1 to the number of annotations

Example: numberToReturn=20

Returns

The annotations that do not belong to any folder represented as a stream of either XML or JSON

Example XML

        <annotations total="1">
           <annotation type="journal" uri="/young-men/duty-to-god/priest/live/learn" locale="eng" id="101" person-id="11" xmlns="http://lds.org/schema/annotation">
              <note uri="journalForm">
                 <content>
                    <html xmlns="http://lds.org/schema/ldshtml/v1">
                       <body>
                          <p>This is a new live worthy Journal entry.</p>
                       </body>
                    </html>
                 </content>
              </note>
              <device>web</device>
              <tags>
                 <tag>journal</tag>
              </tags>
              <timestamp>2011-02-16T10:21:35.113-07:00</timestamp>
           </annotation>
        </annotations>

Example JSON

        {"annotations": {
           "@total": "1",
           "annotation":    {
              "@type": "journal",
              "@uri": "/young-men/duty-to-god/priest/live/learn",
              "@locale": "eng",
              "@id": "101",
              "@person-id": "11",
              "note":       {
                 "@uri": "journalForm",
                 "content": "<html xmlns=\"http://lds.org/schema/ldshtml/v1\"><body><p>This is a new live worthy Journal entry.<\/p><\/body><\/html>"
              },
              "device": "web",
              "tags": {"tag": "journal"},
              "timestamp": "2011-02-16T10:21:35.113-07:00"
           }
        }}

Create and Update Annotations

Create and store new annotations or update existing ones

Method

/annotation

Example XML

  PUT https://tech.lds.org/ws/annotation/v1.3/Services/rest/annotation HTTP/1.1
  Accept: application/xml
  Content-Type: application/xml
 
    <annotations>
       <annotation id="12980721703868980441" locale="eng" type="journal" uri="/young-men/duty-to-god/priest/live/learn" person-id="" xmlns="http://lds.org/schema/annotation">
          <note uri="journalForm">
             <content>
                <html xmlns="http://lds.org/schema/ldshtml/v1">
                   <body>
                      <p>This is a new live worthy Journal entry.</p>
                   </body>
                </html>
             </content>
          </note>
          <source>http://lds.org/young-men/duty-to-god< /source>
          <device>web</device>
          <tags>
             <tag>journal</tag>
          </tags>
          <timestamp>2011-02-17T01:02:03.321-07:00</timestamp>
       </annotation>
       <annotation id="9001" locale="eng" type="bookmark" uri="/scriptures/ot/gen/1" person-id="" xmlns="http://lds.org/schema/annotation">
          <bookmark offset="-1" uri="/scriptures/nt/romans/4.4">
             <name>New Testament Bookmark</name>
          </bookmark>
          <timestamp>2011-02-17T01:02:03.123-07:00</timestamp>
       </annotation>
    </annotations>

Example JSON

  PUT https://tech.lds.org/ws/annotation/v1.3/Services/rest/annotation HTTP/1.1
  Accept: application/json
  Content-Type: application/json
 
    {"annotations": {
       "annotation":    [
                {
             "@id": "9001",
             "@locale": "eng",
             "@type": "bookmark",
             "@uri": "/scriptures/ot/gen/1",
             "@person-id": "",
             "bookmark":          {
                "@offset": "-1",
                "@uri": "/scriptures/nt/romans/4.4",
                "name": "New Testament Bookmark"
             },
             "timestamp": "2011-02-17T01:02:03.123-07:00"
          },
                {
             "@type": "journal",
             "@uri": "/young-men/duty-to-god/priest/live/learn",
             "@locale": "eng",
             "@id": "12980721703868980441",
             "@person-id": "",
             "note":          {
                "@uri": "journalForm",
                "content": "<html xmlns=\"http://lds.org/schema/ldshtml/v1\"><body><p>This is a new Journal entry.<\/p><\/body><\/html>"
             },
             "source": "http://lds.org/young-men/duty-to-god",
             "device": "web",
             "tags": {"tag": "journal"},
             "timestamp": "2011-02-17T01:02:03.321-07:00"
          }
       ]
    }}

HTTP Body - Also refer to the Annotation schema

annotations (optional) - Root element name for multiple annotations

Valid values: <annotations>

Example: <annotations>...</annotations>

annotation (required) - The annotation represented as a stream. This application uses Jettison for reading streams as json and Stax for reading streams as xml. If you are accessing this api over HTTP, you can toggle which is used by indicating ’application/xml’ or ’application/json’ in the Accept and Content-Type headers.

Valid values: <annotation...>...</annotation>

Example: <annotation...>...</annotation>

person-id (required attribute) - Specifies the logged-in users LDS Account ID. This value can be left blank (person-id="") because the service will overwrite its value with the LDS Account ID of the logged-in user before it is written.

Valid values: Valid LDS Account ID

Example: person-id=""

id (required attribute) - The unique identifier for the annotation. The id only needs to be unique to the user's own repository.

Valid values: Any combination of alpha-numeric characters

Example: id="41920393892992928"

locale (required attribute) - The locale of the annotation.

Valid values: any valid locale code

Example: locale="eng"

type (required attribute) - The type of the annotation. Must be one of the following values:

highlight - A highlight is a location and range specified on the document/paragraph/word level. The highlight type requires at least one highlight element, may contain a note element, and can contain no bookmark or refs elements.

bookmark - A bookmark is a specific location in a document and may have a note attached to it. The bookmark type requires only one bookmark element and can contain no highlights or refs elements.

journal - A Journal Entry doesn't relate to any specific passage in particular. It is simply an annotation object with a note attached. The journal type requires only one note element and can contain no bookmark, highlights, or refs elements.

reference - A cross reference is a link between a block of text and another location. The reference type requires at least one highlight and ref elements and can contain no bookmark elements.

Valid values: highlight, bookmark, journal, reference

Example: type="highlight"

uri (optional attribute) - The annotations’ Uniform Resource Identifier (uri). This is always a document level URI. So, in the scriptures for example, it refers to a chapter. In the ensign it might refer to a specific article.

Valid values: Any url

Example: uri="/scriptures/bofm/1-ne/3" or uri="/general-conference/2010/04/welcome-to-conference" or uri="/ensign/2010/01/hold-on-a-little-longer"

scope (optional attribute) - The annotations’ scope

Valid values: Any text

Example: scope=2-3

status (optional attribute) - The annotations’ status attribute.

Valid values: trashed or deleted

Example: status="trashed"

contentVersion (optional attribute) - The annotations’ content version attribute.

Valid values: Positive integer values

Example: contentVersion="1"

highlights (optional) - The wrapper element for list of highlight elements.

Valid values: <highlights>

Example: <highlights>...</highlights>

highlight (required) - The highlight element encapsulates a location in a document and an associated kind of marking at that location.

Valid values: <highlight.../>

Example: <highlight uri="/scriptures/nt/matt/1.3" offset-start="-1" offset-end="25" color="AAF6FF" style="red-underline"/>

uri (required attribute) - The URI and suffix needed to define a specific location in a specific document.

Valid values: Any URI and suffix. Valid suffix names include: "head", "s", "t", "p", "f", "closing", "fn", and ""(no suffix name is specified for scriptures).

Example: uri="/scriptures/nt/matt/1.3", uri="/general-conference/2010/10/as-we-meet-together-again.p6"

offset-start (required attribute) - The word offset that marks the start of this highlight range. It is one based, so zero is not allowed. A value of -1 means the beginning of the paragraph.

Valid values: -1, 1-end

Example: offset-start="-1"

offset-end (required attribute) - The word offset that marks the end of this highlight range. It is one based, so zero is not allowed. A value of -1 means the end of the paragraph.

Valid values: -1, 1-end

Example: offset-end="25"

color (required attribute) - The color of the highlight. This currently only applies to non underlined style highlights on the web. That is, the color is ignored if the style is underlined on the web, the underline is always red. Currently the web UI interface only allows 4 colors, but this value could potentially support any color that can be described in a hex web color.

Valid values: FFF8AA(yellow), AAF6FF(blue), D6FFAA(green), FFC2E9(pink)

Example: color="AAF6FF"

style (optional attribute) - The style attribute is either empty, meaning the highlighter look, or "red-underline" which makes the text underlined.

Valid values: empty or red-underline

Example: style="red-underline"

mapping (optional attribute) - The mapping attribute

Valid values:

Example:

note (optional) - There are two kinds of notes. Notes that relate to a specific location, like a note attached to a highlight. There are also notes that have no location information, and these are called Journal Entries.

Valid values: <note>

Example: <note uri="/general-conference/2010/04/welcome-to-conference">...</note>

uri (optional attribute) - This is a paragraph level URI. See the URI explanation with Highlight. If this attribute is missing, than this annotation should have the type of "journal" for journal entry.

Valid values: Any URI

Example: uri="/general-conference/2010/04/welcome-to-conference"

mapping (optional attribute) - The mapping attribute

Valid values:

Example:

title (optional) - This is the title for the note.

Valid values: Any text

Example: <title>My title goes here</title>

content (required) - This is the content for the note, the actual text, but it is not plain text. It must be formatted according to the ldshtml schema, which basically means regular HTML with no scripting injection attacks. The text is limited to 20,000 characters per p tag.

Valid values: Formatted according to the ldshtml schema

Example: <content><html xmlns="http://lds.org/schema/ldshtml/v1"><body><p>My note text.</p></body></html></content>

folders (optional) - The element wrapper for folder elements. A folder is used to group annotations. Annotations may be in more than one folder. You can order annotations in a folder. The folders specified must have been previously created or an error will be returned.

Valid values: <folders>

Example: <folders>...</folders>

folder (required) - The folder element specifies which folder this annotation belongs to.

Valid values: <folder...>

Example: <folder uri="/study-tools/folders/11/1234"/>

uri (required attribute) - The URI specifies the folder to include this annotation. The URI must start with "/study-tools/folders/" then contains the person-Id and then the folderId (guid).

Valid values: /study-tools/folders/{person-Id}/{folderId}

Example: uri="/study-tools/folders/11/1234"

bookmark (optional) - A bookmark marks a location so that a user can resume reading at a certain location.

Valid values: <bookmark>

Example: <bookmark uri="/scriptures/jst/jst-gen/9.1" offset="-1"><name>My name</name></bookmark>

uri (required attribute) - The paragraph level URI for this bookmark. See the URI explanation with Highlight.

Valid values: Any URI

Example: uri="/scriptures/jst/jst-gen/9.1"

offset (required attribute) - The word offset that marks the word for this bookmark. It is one based, so zero is not allowed. A value of -1 means the beginning of the paragraph.

Valid values: -1, 1-end

Example: offset="-1"

name (optional) - The name of the bookmark. The name is limited to 256 characters.

Valid values: Any text

Example: <name>My bookmark name</name>

groups (optional) - This is a forward looking element that is not being used at this time.

Valid values:

Example:

source (optional) - The source element is used to describe the source application that created the annotation. For example iOS uses "iOS Gospel Library" and LDS.org uses "http://lds.org".

Valid values: Any text

Example: <source>http://lds.org/young-men/duty-to-god</source>

device (optional) - The device element is used to specify the name of the device that created the annotation.

Valid values: web, iphone, android, webos, winmo, blackberry, or ipad

Example: <device>iphone</device>

tags (optional) - A wrapper for tag elements.

Valid values: <tags>

Example: <tags><tag>MyTag1</tag><tag>MyTag2</tag></tags>

tag (required) - A tag is similar to a folder except you cannot order the annotations and they do not have to be created before hand.

Valid values: <tags>

Example: <tag>MyTag1</tag>

public (optional attribute) - The public attribute is a part of a sharing mechanism and is unused at this time.

Valid values: true or false

Example: public="true"

refs (optional) - A wrapper for ref elements.

Valid values: <refs>

Example: <refs>...</refs>

ref (required) - A reference is a link out bound from some text to another location in the database. It's short for cross reference. The content is the name of the reference. Each reference may point to a different set of destination verses. This allows a user to add their own "footnotes" in the scriptures or any other library content.

Valid values: <ref...>

Example: <ref uri="/scriptures/nt/matt/1.3-7">My reference name</ref>

uri (required) - The URI for a cross reference follows all the paragraph level URI details specified above in the explanation with Highlight, but it also allows for specifying more than one destination paragraph.

Valid values: Any URI and suffix. Valid suffix names include: "head", "s", "t", "p", "f", "closing", "fn", and ""(no suffix name is specified for scriptures).

Example:

Contiguous - uri="/scriptures/nt/matt/1.3-7" and uri="/general-conference/2010/10/as-we-meet-together-again.p6-p8"

Discontiguous - uri="/scriptures/nt/matt/1.3,6,8,9" and uri="/general-conference/2010/10/as-we-meet-together-again.p6,p9-p12"

public (optional attribute) - The public attribute is a part of a sharing mechanism and is unused at this time.

Valid values: true or false

Example: public="true"

timestamp (required) - The time that the annotation was written. The client is responsible for creating this time.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <timestamp>2011-02-14T10:00:00.123-07:00</timestamp>

Returns

Returns an HTTP 204 No Content on success

Delete Annotations Using Optional Query Parameters

Deletes the annotations for the logged-in user using optional query parameter criteria.

Method

/annotations

Example

  DELETE https://tech.lds.org/ws/annotation/v1.3/Services/rest/annotations?delStatus=trashed&type=bookmark&since=2011-02-14T10:00:00.123-07:00 HTTP/1.1
  Accept: application/json

Parameters

delStatus (optional) - The value to write to the annotations’ status attribute. The default value is deleted.

Valid values: trashed or deleted

Example: delStatus=trashed

locale (optional) - The annotations’ locale

Valid values: any valid locale code

Example: locale=eng

uri (optional) - The annotations’ uri

Valid values: Any url

Example: uri=/scriptures/bofm/1-ne/3

scope (optional) - The annotations’ scope

Valid values: Any text

Example: scope=2-3

type (optional) - The type of the annotation. Can contain more than one type when delimited with comma's.

Valid values: highlight, bookmark, journal, reference

Example: type=highlight,bookmark

since (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is greater than or equal to the time stamp specified by since.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: since=2011-02-14T10:00:00.123-07:00

before (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is less than the time stamp specified by before.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: before=2011-02-14T10:00:00.123-07:00

status (optional) - The annotations’ status attribute. The default (status not specified) is to return annotations that have no status attribute value. The status values may contain more than one value when delimited with comma's.

Valid values: all, trashed, deleted

Example: status=trashed,deleted

tag (optional) - The annotations’ tag element values. The tag values may contain more than one value when delimited with comma's.

Valid values: Any tag value

Example: tag=Favorite

searchPhrase (optional) - The phrase to use for searching annotation content specified by searchFields. The search will be case and diacritic insensitive.

Valid values: Any phrase of words with spaces replaced by %20

Example: searchPhrase=love%20at%20home

searchFields (optional) - The annotation fields to search for the phrase specified in searchPhrase. The match is true is the searchPhrase is found in any of the searchFields specified. The default is to search all annotation content.

Valid values: Any combination of "tag", "note", and "name" that are comma delimited.

Example: searchFields=tag,note

Delete Annotations By ID's

Deletes annotations specified by IDs

Method

/annotation

Example

  DELETE https://tech.lds.org/ws/annotation/v1.3/Services/rest/annotation?id=123,987&delStatus=trashed HTTP/1.1
  Accept: application/xml

Parameters

id (required) - The annotation identifiers to be deleted. Multiple id's can be specified with a comma delimited list.

Valid values: Any text

Example: id=123,987

delStatus (optional) - The value to write to the annotations’ status attribute. The default value is deleted.

Valid values: trashed or deleted

Example: delStatus=trashed

Delete Annotations By ID

Deletes a specific annotation. Note: Annotation IDs are specific to the user.

Method

/annotation/{annotationId}

Example

  DELETE https://tech.lds.org/ws/annotation/v1.3/Services/rest/annotation/314159 HTTP/1.1
  Accept: application/xml

Parameters

annotationId (required) - The annotation’s identifier

Valid values: Any text

Example: 314159

delStatus (optional) - The value to write to the annotation status attribute. The default value is deleted.

Valid values: trashed or deleted

Example: delStatus=trashed

Folder Methods

Retrieve Folders Using Optional Query Parameters

Get folders for the logged-in user using optional query parameter criteria.

Method

/folders

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/folders?folderStatus=trashed HTTP/1.1
  Accept: application/xml

Parameters

folderStatus (optional) - The value of the folder status attribute to use in the search. If the folderStatus parameter is not specified then all folders that have not been trashed or deleted will be returned.

Valid values: trashed or deleted

Example: folderStatus=trashed

meta (optional) - The boolean value that will determine if meta-data will be returned. The default value is true.

Valid values: true or false

Example: meta=false

The following parameters are used in calculating annotation meta-data and are only used if meta=true

locale (optional) - The annotations’ locale

Valid values: any valid locale code

Example: locale=eng

uri (optional) - The annotations’ uri

Valid values: Any url

Example: uri=/scriptures/bofm/1-ne/3

scope (optional) - The annotations’ scope

Valid values: Any text

Example: scope=2-3

type (optional) - The type of the annotation. Can contain more than one type when delimited with comma's.

Valid values: highlight, bookmark, journal, reference

Example: type=highlight,bookmark

since (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is greater than or equal to the time stamp specified by since.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: since=2011-02-14T10:00:00.123-07:00

before (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is less than the time stamp specified by before.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: before=2011-02-14T10:00:00.123-07:00

status (optional) - The annotations’ status attribute. The default (status not specified) is to return annotations that have no status attribute value. The status values may contain more than one value when delimited with comma's.

Valid values: all, trashed, deleted

Example: status=trashed,deleted

tag (optional) - The annotations’ tag element values. The tag values may contain more than one value when delimited with comma's.

Valid values: Any tag value

Example: tag=Favorite

searchPhrase (optional) - The phrase to use for searching annotation content specified by searchFields. The search will be case and diacritic insensitive.

Valid values: Any phrase of words with spaces replaced by %20

Example: searchPhrase=love%20at%20home

searchFields (optional) - The annotation fields to search for the phrase specified in searchPhrase. The match is true is the searchPhrase is found in any of the searchFields specified. The default is to search all annotation content.

Valid values: Any combination of "tag", "note", and "name" that are comma delimited.

Example: searchFields=tag,note

Returns

The folders that fit the search criteria represented as a stream of either XML or JSON

Example

        <folders person-id="11" xmlns="http://lds.org/schema/folder">
           <folder guid="1">
              <label>Folder 1</label>
              <desc>My Folder 1</desc>
              <timestamp>2011-02-03T02:01:00.000-06:00</timestamp>
              <order>
                 <id>2011</id>
                 <id>2012</id>
              </order>
           </folder>
           <folder guid="2">
              <label>Folder 2</label>
              <desc>Description 2</desc>
              <timestamp>2011-01-01T01:00:00.000-06:00</timestamp>
              <order>
                 <id>1234</id>
              </order>
           </folder>
           <folder guid="7">
              <label>Folder 7</label>
              <desc>Description 7</desc>
              <timestamp>2010-12-03T02:01:00.000-06:00</timestamp>
              <order>
                 <id>3021</id>
                 <id>3022</id>
              </order>
           </folder>
           <folder guid="8">
              <label>Folder 8</label>
              <desc>My Folder 8</desc>
              <timestamp>2010-12-03T02:01:00.000-06:00</timestamp>
           </folder>
        </folders>

Retrieve Folder By Folder Id

Get a folder for the logged-in user by folder ID.

Method

/folder/{folderId}

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/folder/1234 HTTP/1.1
  Accept: application/xml

Parameters

folderId (required) - The id (guid) of the folder to be returned.

Valid values: Any text

Example: 1234

Returns

The folder with the folderId represented as a stream of either XML or JSON

Example

        <folder guid="1" xmlns="http://lds.org/schema/folder">
           <label>Folder 1</label>
           <desc>My Folder 1</desc>
           <timestamp>2010-12-03T02:01:00.000-06:00</timestamp>
           <order>
              <id>2011</id>
              <id>2012</id>
           </order>
        </folder>

Create and Update Multiple Folders

Create or update the folders for the logged-in user. Folders that used to exist but are not specified in this call will have their status attribute set to deleted.

Method

/folders

Example

  PUT https://tech.lds.org/ws/annotation/v1.3/Services/rest/folders HTTP/1.1
  Accept: application/xml
  Content-Type: application/xml
 
    <folders person-id="" xmlns="http://lds.org/schema/folder">
       <folder guid="1">
          <label>Folder 1</label>
          <desc>Description 1</desc>
          <timestamp>2010-08-01T01:00:00.12345-06:00</timestamp>
       </folder>
       <folder guid="2">
          <label>Folder 2</label>
          <desc>Description 2</desc>
          <timestamp>2010-08-02T02:00:00.000-06:00</timestamp>
       </folder>
       <folder guid="7">
          <label>Folder 7</label>
          <desc>Description 7</desc>
          <timestamp>2010-12-03T02:01:00.000-06:00</timestamp>
          <order>
             <id>3021</id>
             <id>3022</id>
          </order>
       </folder>
    </folders>

</source> HTTP Body - Also refer to the Folder schema

folders (required) - Root element name for multiple folders

Valid values: <folders>

Example: <folders person-id="" xmlns="http://lds.org/schema/folder"><folder...>...</folder></folders>

person-id (required attribute) - This attribute must be specified but its value will be replaced with the logged-in users LDS account ID.

Valid values: Any valid LDS Account ID or ""

Example: person-id=""

xmlns (required attribute) - The XML namespace must be specified as "http://lds.org/schema/folder".

Valid values: http://lds.org/schema/folder

Example: xmlns="http://lds.org/schema/folder"

folder (required) - A folder is used to group annotations. It can also specify annotation order. Folders need to be created before annotations can be associated with them.

Valid values: <folder...>

Example: <folder guid="148389293837">...</folder>

guid (required attribute) - The folder ID (guid) is the unique identifier for the folder. The guid value is used by annotations to specify that they belong to a folder. The annotation folder element uses the following format: uri="/study-tools/folders/{person-id}/{guid}.

Valid values: Any unique (for the user) text

Example: guid="148389293837"

label (required) - The name of the folder.

Valid values: Any text up to 256 characters.

Example: <label>My folder label</label>

desc (optional) - The description of the folder.

Valid values: Any text up to 1000 characters.

Example: <label>My folder label</label>

timestamp (required) - The date and time this folder was last modified. It is only updated when the user modifies either the name or description of the folder. Adding or removing items in the folder does NOT change the folder's time stamp.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <timestamp>2011-02-14T10:00:00.123-07:00</timestamp>

order (optional) - This is a wrapper for id elements that specify the order of annotations in the folder.

Valid values: <order>

Example: <order><id>123</id><id>124</id></order>

id (required) - Specifies the annotation ID for ordering.

Valid values: <id>123</id>

Example: <id>123</id>

Returns

Returns an HTTP 204 No Content on success

Create a Single Folder

Create or update a folder specified by folder ID (guid) for the logged-in user.

Method

/folder/{folderId}

Example

  PUT https://tech.lds.org/ws/annotation/v1.3/Services/rest/folder/1 HTTP/1.1
  Accept: application/xml
  Content-Type: application/xml
 
     <folder guid="1" xmlns="http://lds.org/schema/folder">
        <label>Folder 1</label>
        <desc>Description 1</desc>
        <timestamp>2010-08-01T01:00:00.12345-06:00</timestamp>
     </folder>

Parameters

folderId (required) - The id (guid) of the folder to be created. This value must match the guid attribute value of the folder element.

Valid values: Any text

Example: 1

HTTP Body - Also refer to the Folder schema

See - Create and Update Multiple Folders

Returns

Returns an HTTP 204 No Content on success

Delete Folders

Delete the folders for the logged-in user. The folder will be marked as trashed or deleted depending on the value of the delStatus parameter.

Method

/folders

Example

  DELETE https://tech.lds.org/ws/annotation/v1.3/Services/rest/folders?delStatus=trashed HTTP/1.1

Parameters

delStatus (optional) - The value that will be saved in the folder's status attribute. The default is deleted.

Valid values: trashed or deleted

Example: delStatus=trashed

Returns

Returns an HTTP 204 No Content on success

Delete Folder

Delete a folder specified by folder ID (guid) for the logged-in user. The folder will be marked as trashed or deleted depending on the value of the delStatus parameter.

Method

/folder/{folderId}

Example

  DELETE https://tech.lds.org/ws/annotation/v1.3/Services/rest/folder/1?delStatus=trashed HTTP/1.1

Parameters

folderId (required) - The folder ID (guid) value of the folder to be deleted.

Valid values: Any existing folder ID (guid)

Example: 1

delStatus (optional) - The value that will be saved in the folder status attribute. The default is deleted.

Valid values: trashed or deleted

Example: delStatus=trashed

Returns

Returns an HTTP 204 No Content on success

Tag Methods

Retrieve Tags

Get the tags associated with annotations

Method

/tags

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/tags?meta=false HTTP/1.1

Parameters

meta (optional) - The boolean value that will determine if meta-data will be returned. The default value is true.

Valid values: true or false

Example: meta=false

The following parameters are used in calculating which annotations to look in for tags

locale (optional) - The annotations’ locale

Valid values: any valid locale code

Example: locale=eng

uri (optional) - The annotations’ uri

Valid values: Any url

Example: uri=/scriptures/bofm/1-ne/3

scope (optional) - The annotations’ scope

Valid values: Any text

Example: scope=2-3

type (optional) - The type of the annotation. Can contain more than one type when delimited with comma's.

Valid values: highlight, bookmark, journal, reference

Example: type=highlight,bookmark

since (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is greater than or equal to the time stamp specified by since.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: since=2011-02-14T10:00:00.123-07:00

before (optional) - A time stamp used to compare against annotation timestamp elements. The comparison is true if the annotation timestamp is less than the time stamp specified by before.

Valid values: Any valid ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: before=2011-02-14T10:00:00.123-07:00

status (optional) - The annotations’ status attribute. The default (status not specified) is to return annotations that have no status attribute value. The status values may contain more than one value when delimited with comma's.

Valid values: all, trashed, deleted

Example: status=trashed,deleted

tag (optional) - The annotations’ tag element values. The tag values may contain more than one value when delimited with comma's.

Valid values: Any tag value

Example: tag=Favorite

searchPhrase (optional) - The phrase to use for searching annotation content specified by searchFields. The search will be case and diacritic insensitive.

Valid values: Any phrase of words with spaces replaced by %20

Example: searchPhrase=love%20at%20home

searchFields (optional) - The annotation fields to search for the phrase specified in searchPhrase. The match is true is the searchPhrase is found in any of the searchFields specified. The default is to search all annotation content.

Valid values: Any combination of "tag", "note", and "name" that are comma delimited.

Example: searchFields=tag,note

Returns

The tags that fit the search criteria represented as a stream of either XML or JSON

Example XML

        <tags total="2">
           <tag>testimony</tag>
           <tag>love</tag>
        </tags>

Example JSON

        {"tags": {
           "@total": "2",
           "tag":    [
              "testimony",
              "love"
           ]
        }}

Sync Methods

The following sync methods allow mobile clients to sync changes when they connect to the Annotation service. The mobile client submits to the service any changes it has made since a given date. The service resolves these changes with any that have been made by other clients since that date and responds back with any new changes that must be applied to bring the mobile device up-to-date. The change conflict resolution algorithm uses a "last in wins" approach (the one with the latest "timestamp" wins). The data format is generally the same for both changes submitted by the client and changes returned by the service.

Sync Annotations

Sync annotations with the server

Method

/sync/annotations

Example

  PUT https://tech.lds.org/ws/annotation/v1.3/Services/rest/sync/annotations HTTP/1.1
  Accept: application/xml
  Content-Type: application/xml
 
    <syncAnnotations xmlns="http://lds.org/schema/annotation">
      <since>2011-02-15T01:00:00.123-06:00</since>
      <clientTime>2011-03-25T09:00:02.123-07:00</clientTime>
      <schemaDate>2011-01-15T12:00:00.000-07:00</schemaDate>
      <changes>
        <annotationId>2011</annotationId>
        <changeType>new</changeType>
        <annotation uri="/test/uri" type="highlight" locale="eng" id="2011" person-id="" xmlns="http://lds.org/schema/annotation">
          <highlights>
            <highlight uri="/test/uri/para1" color="FFF8AA" offset-start="-1" offset-end="2"/>
          </highlights>
          <device>iphone</device>
          <tags>
            <tag>MyTag1</tag>
            <tag>MyTag2</tag>
          </tags>
          <timestamp>2011-02-16T01:00:00.009-07:00</timestamp>
        </annotation>
        <timestamp>2011-02-16T01:00:00.009-07:00</timestamp>
      </changes>
      <changes>
        <annotationId>2012</annotationId>
        <changeType>trash</changeType>
        <annotation uri="/test/uri" type="highlight" locale="eng" id="2012" person-id="" xmlns="http://lds.org/schema/annotation">
          <highlights>
            <highlight uri="/test/uri/para1" color="FFF8AA" offset-start="-1" offset-end="2"/>
          </highlights>
          <device>iphone</device>
          <tags>
            <tag>SyncMyTag2011</tag>
            <tag>SyncMyTag22012</tag>
          </tags>
          <timestamp>2011-02-16T01:00:00.009-07:00</timestamp>
        </annotation>
        <timestamp>2011-02-16T01:00:00.009-07:00</timestamp>
      </changes>
      <changes>
        <annotationId>2013</annotationId>
        <changeType>delete</changeType>
        <timestamp>2011-02-16T01:00:00.009-07:00</timestamp>
      </changes>
    </syncAnnotations>

HTTP Body

syncAnnotations (required) - The root element

Valid values: <syncAnnotations xmlns="http://lds.org/schema/annotation">

Example: <syncAnnotations xmlns="http://lds.org/schema/annotation">

since (required) - Specifies the time period used for syncing

Valid values: ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <since>2011-02-15T01:00:00.123-06:00</since>

clientTime (optional) - Specifies the current client time. This value is used to adjust the timestamp values of in-coming client changes to be in server time (AdjustedTimeStamp = PassedInTimestamp + (currentServerTime - clientTime). This value is also used to adjust the out-going timestamp values to be in client time (AdjustedTimeStamp = StoredOutgoingTimestamp - (currentServerTime - clientTime). All timestamp values are stored on the server in server time.

Valid values: ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <clientTime>2011-03-25T09:00:02.123-06:00</clientTime>

before (returned) - Specifies the current time on the server when the sync took place. This time should be used as the since time by the client on the next sync/annotations call.

Valid values: ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <before>2011-02-15T01:00:00.123-06:00</before>

timeDiff (returned) - Specifies the the time difference from the current Server time minus clientTime. All in coming change timestamps will be adjusted (added) by this duration before they are stored to the server. All returning timestamps will be adjusted (subtracted) by this duration before they are returned.

Valid values: ISO 8601 duration with the format: PT[n]H[n]M[n]S

Example: <timeDiff>PT4M23.562S</timeDiff>

schemaDate (required) - The date of the schema that the client was built against. This date will be used to try and keep new annotation element and attribute values that have been saved on the server (using a different client) that this client does not know about.

Valid values: ISO 8601 dateTime with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <schemaDate>2011-01-15T12:00:00.000-07:00</schemaDate>

changes (required) - The wrapper for each change

Valid values: <changes>

Example: <changes>...</changes>

annotationId (required) - The id of the annotation to be synced.

Valid values: Any valid annotation value

Example: <annotationId>2011</annotationId>

changeType (required) - Specifies that type of change being made

Valid values: new, trash, or delete

Example: <changeType>new</changeType>

annotation (optional) - The annotation to be synced. This is optional for changeType trash or delete.

Valid values: See annotation creation

Example: <annotation ...>...</annotation>

timestamp (required) - The time that the change was made. This value must match the timestamp value in the annotation.

Valid values: ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <timestamp>2011-02-16T01:00:00.009-07:00</timestamp>

Returns

The annotations that have been changed since the time specified represented as a stream of either XML or JSON

Example XML

        <syncAnnotations xmlns="http://lds.org/schema/annotation">
           <since>2011-02-15T01:00:00.123-06:00</since>
           <before>2011-02-17T10:17:19.174-07:00</before>
           <timeDiff>PT4M23.562S</timeDiff>
           <changes>
              <annotationId>101</annotationId>
              <changeType>trash</changeType>
              <timestamp>2011-02-16T01:00:00.009-07:00</timestamp>
           </changes>
           <changes>
              <annotationId>102</annotationId>
              <changeType>new</changeType>
              <annotation type="journal" uri="/young-men/duty-to-god/priest/live/learn" locale="eng" id="102" person-id="11">
                 <note uri="journalForm">
                    <content>
                       <html xmlns="http://lds.org/schema/ldshtml/v1">
                          <body>
                             <p>This is a new live worthy Journal entry.</p>
                          </body>
                       </html>
                    </content>
                 </note>
                 <device>web</device>
                 <tags>
                    <tag>journal</tag>
                 </tags>
                 <timestamp>2011-02-16T10:21:35.113-07:00</timestamp>
              </annotation>
              <timestamp>2011-02-16T10:21:35.113-07:00</timestamp>
           </changes>
           <changes>
              <annotationId>103</annotationId>
              <changeType>delete</changeType>
              <timestamp>2011-02-16T01:00:00.009-07:00</timestamp>
           </changes>
        </syncAnnotations>

Example JSON

        {"syncAnnotations": {
           "since": "2011-02-15T01:00:00.123-06:00",
           "before": "2011-02-17T10:22:58.227-07:00",
           "timeDiff": "PT4M23.562S",
           "changes":    [
                    {
                 "annotationId": 101,
                 "changeType": "trash",
                 "timestamp": "2011-02-16T01:00:00.009-07:00"
              },
                    {
                 "annotationId": "102",
                 "changeType": "new",
                 "annotation":          {
                    "@type": "journal",
                    "@uri": "/young-men/duty-to-god/priest/live/learn",
                    "@locale": "eng",
                    "@id": "102",
                    "@person-id": "11",
                    "note":             {
                       "@uri": "journalForm",
                       "content": "<html xmlns=\"http://lds.org/schema/ldshtml/v1\"><body><p>This is a new live worthy Journal entry.<\/p><\/body><\/html>"
                    },
                    "device": "web",
                    "tags": {"tag": "journal"},
                    "timestamp": "2011-02-16T10:21:35.113-07:00"
                 },
                 "timestamp": "2011-02-16T10:21:35.113-07:00"
              },
                    {
                 "annotationId": 103,
                 "changeType": "delete",
                 "timestamp": "2011-02-16T01:00:00.009-07:00"
              }
           ]
        }}

Sync Folders

Sync folders with the server

Method

/sync/folders

Example

  PUT https://tech.lds.org/ws/annotation/v1.3/Services/rest/sync/folders HTTP/1.1
  Accept: application/xml
  Content-Type: application/xml
 
    <syncFolders xmlns="http://lds.org/schema/folder">
           <since>2010-01-01T01:00:00-06:00</since>
           <clientTime>2011-03-25T09:00:02.123-07:00</clientTime>
           <schemaDate>2011-01-15T12:00:00.000-07:00</schemaDate>
           <changes>
              <folderId>1</folderId>
              <changeType>new</changeType>
          <folder guid="1">
                <label>Folder 1</label>
                <timestamp>2011-02-15T01:00:01-06:00</timestamp>
              </folder>
              <timestamp>2011-02-15T01:00:01-06:00</timestamp>
           </changes>
    </syncFolders>

HTTP Body

syncFolders (required) - The root element

Valid values: <syncFolders xmlns="http://lds.org/schema/folder">

Example: <syncFolders xmlns="http://lds.org/schema/folder">

since (required) - Specifies the time period used for syncing

Valid values: ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <since>2011-02-15T01:00:00.123-06:00</since>

clientTime (optional) - Specifies the current client time. This value is used to adjust the timestamp values of in-coming client changes to be in server time (AdjustedTimeStamp = PassedInTimestamp + (currentServerTime - clientTime). This value is also used to adjust the out-going timestamp values to be in client time (AdjustedTimeStamp = StoredOutgoingTimestamp - (currentServerTime - clientTime). All timestamp values are stored on the server in server time.

Valid values: ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <clientTime>2011-03-25T09:00:02.123-06:00</clientTime>

before (returned) - Specifies the current time on the server when the sync took place. This time should be used as the since time by the client on the next sync/folders call.

Valid values: ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <before>2011-02-15T01:00:00.123-06:00</before>

timeDiff (returned) - Specifies the the time difference from the current Server time minus clientTime. All in coming change timestamps will be adjusted (added) by this duration before they are stored to the server. All returning timestamps will be adjusted (subtracted) by this duration before they are returned.

Valid values: ISO 8601 duration with the format: PT[n]H[n]M[n]S

Example: <timeDiff>PT4M23.562S</timeDiff>

schemaDate (required) - The date of the schema that the client was built against. This date will be used to try and keep new folder element and attribute values that have been saved on the server (using a different client) that this client does not know about.

Valid values: ISO 8601 date with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <schemaDate>2011-01-15T12:00:00.000-07:00</schemaDate>

changes (required) - The wrapper for each change

Valid values: <changes>

Example: <changes>...</changes>

folderId (required) - The id of the folder to be synced.

Valid values: Any valid folder id value

Example: <folderId>2011</folderId>

changeType (required) - Specifies that type of change being made

Valid values: new, trash, or delete

Example: <changeType>new</changeType>

folder (optional) - The folderto be synced. This is optional for changeType trash or delete.

Valid values: See folder creation

Example: <folder ...>...</folder>

timestamp (required) - The time that the change was made. This value must match the timestamp value in the folder.

Valid values: ISO 8601 date time with the format: YYYY-MM-DDThh:mm:ss.sTZD

Example: <timestamp>2011-02-16T01:00:00.009-07:00</timestamp>

Returns

The folders that have changed since the time specified represented as a stream of either XML or JSON

Example XML

        <syncFolders xmlns="http://lds.org/schema/folder">
           <since>2010-01-01T01:00:00.000-06:00</since>
           <before>2011-02-17T11:14:31.436-07:00</before>
           <timeDiff>PT4M23.562S</timeDiff>
           <changes>
              <folderId>7</folderId>
              <changeType>new</changeType>
              <folder guid="7">
                 <label>Folder 7</label>
                 <desc>Description 7</desc>
                 <timestamp>2010-12-03T02:01:00.000-06:00</timestamp>
                 <order>
                    <id>3021</id>
                    <id>3022</id>
                 </order>
              </folder>
              <timestamp>2010-12-03T02:01:00.000-06:00</timestamp>
           </changes>
           <changes>
              <folderId>10</folderId>
              <changeType>trash</changeType>
              <timestamp>2011-01-26T14:11:42.600-07:00</timestamp>
           </changes>
           <changes>
              <folderId>11</folderId>
              <changeType>delete</changeType>
              <timestamp>2011-01-26T14:11:42.600-07:00</timestamp>
           </changes>
        </syncFolders>

Example JSON

        {"syncFolders": {
           "since": "2010-01-01T01:00:00.000-06:00",
           "before": "2011-02-17T11:24:45.496-07:00",
           "timeDiff": "PT4M23.562S",
           "changes":    [
                    {
                 "folderId": 7,
                 "changeType": "new",
                 "folder":          {
                    "@guid": "7",
                    "label": "Folder 7",
                    "desc": "Description 7",
                    "timestamp": "2010-12-03T02:01:00.000-06:00",
                    "order": {"id":             [
                       3021,
                       3022
                    ]}
                 },
                 "timestamp": "2010-12-03T02:01:00.000-06:00"
              },
                    {
                 "folderId": 10,
                 "changeType": "trash",
                 "timestamp": "2011-01-26T14:11:42.600-07:00"
              },
                    {
                 "folderId": 11,
                 "changeType": "delete",
                 "timestamp": "2011-01-26T14:11:42.600-07:00"
              }
           ]
        }}

Info Methods

Ping

Ping the service

Method

/info/ping

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/info/ping HTTP/1.1
  Accept: application/xml

Parameters

Returns

The response status represented as a stream of either XML or JSON

Example XML

        <responseStatus>
           <good>true</good>
           <message>pong!</message>
        </responseStatus>

Example JSON

        {"responseStatus": {
           "good": true,
           "message": "pong!"
        }}

Backend Ping

Ping the service backend

Method

/backend/ping

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/backend/ping HTTP/1.1
  Accept: application/xml

Parameters

Returns

The backend response status represented as a stream of either XML or JSON

Example XML

        <responseStatus>
           <good>true</good>
           <message>Backend is responding</message>
        </responseStatus>

Example JSON

        {"responseStatus": {
           "good": true,
           "message": "Backend is responding"
        }}

Version

Return the service version information

Method

/info/version

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/info/version HTTP/1.1
  Accept: application/xml

Parameters

Returns

The version information represented as a stream of either XML or JSON

Example XML

        <systemInfoDto>
           <buildDate>01281451</buildDate>
           <buildEnv>was</buildEnv>
           <buildJdk>1.5.0_07</buildJdk>
           <buildRevision>346</buildRevision>
           <implementationTitle>ws-web</implementationTitle>
           <implementationVendor>LDS Church</implementationVendor>
           <implementationVersion>1.3</implementationVersion>
           <stackVersion>2.1.14</stackVersion>
           <startTime>Wed Feb 16 10:55:32 MST 2011</startTime>
           <upTime>90717910</upTime>
           <version>1.3-rev.346</version>
        </systemInfoDto>

Example JSON

        {"systemInfoDto": {
           "buildDate": "01281451",
           "buildEnv": "was",
           "buildJdk": "1.5.0_07",
           "buildRevision": 346,
           "implementationTitle": "ws-web",
           "implementationVendor": "LDS Church",
           "implementationVersion": 1.3,
           "stackVersion": "2.1.14",
           "startTime": "Wed Feb 16 10:54:12 MST 2011",
           "upTime": 90844692,
           "version": "1.3-rev.346"
        }}

Backend Version

Return the service backend version information

Method

/backend/version

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/backend/version HTTP/1.1
  Accept: application/xml

Parameters

Returns

The service backend version information represented as a stream of either XML or JSON

Example XML

        <versionInfo>
           <personId/>
           <project>
              <name>notebook</name>
              <version>2.1</version>
              <build>
                 <timestamp>Thu Feb 10 14:53:32 MST 2011</timestamp>
                 <revision>372</revision>
              </build>
              <dependencies>
                 <dependency>
                    <groupId>org.lds.marklogic.shared</groupId>
                    <artifactId>common</artifactId>
                    <version>2.9.1</version>
                 </dependency>
              </dependencies>
           </project>
        </versionInfo>

Example JSON

        {"versionInfo": {
           "personId": "",
           "project":    {
              "name": "notebook",
              "version": 2.1,
              "build":       {
                 "timestamp": "Thu Feb 10 14:53:32 MST 2011",
                 "revision": 372
              },
              "dependencies": {"dependency":       {
                 "groupId": "org.lds.marklogic.shared",
                 "artifactId": "common",
                 "version": "2.9.1"
              }}
           }
        }}

Monitor

Return pass/fail results for monitoring

Method

/monitor

Example

  GET https://tech.lds.org/ws/annotation/v1.3/Services/rest/monitor HTTP/1.1
  Accept: application/xml

Parameters

Returns

The results of some monitoring tests represented as a stream of either XML or JSON

Example XML

        <monitorInfo>
           <result>pass</result>
           <time>PT0.017S</time>
           <mlHost>localhost:9001</mlHost>
           <tests>
              <createAnnotation>pass</createAnnotation>
              <getAnnotation>pass</getAnnotation>
              <deleteAnnotation>pass</deleteAnnotation>
              <syncAnnotation>pass</syncAnnotation>
           </tests>
        </monitorInfo>

Example JSON

        {"monitorInfo": {
           "result": "pass",
           "time": "PT0.092S",
           "mlHost": "localhost:9001",
           "tests":    {
              "createAnnotation": "pass",
              "getAnnotation": "pass",
              "deleteAnnotation": "pass",
              "syncAnnotation": "pass"
           }
        }}

Community Services Journal Annotations Service V1.3

Contents

Overview

Technical Overview

Transport Media Types

Base URL

Annotation Methods

Retrieve Annotations Using Optional Query Parameters

Retrieve Annotations By Id

Retrieve Annotations By Folder Id

Retrieve Annotations Not Associated with a Folder

Create and Update Annotations

Delete Annotations Using Optional Query Parameters

Delete Annotations By ID's

Delete Annotations By ID

Folder Methods

Retrieve Folders Using Optional Query Parameters

Retrieve Folder By Folder Id

Create and Update Multiple Folders

Create a Single Folder

Delete Folders

Delete Folder

Tag Methods

Retrieve Tags

Sync Methods

Sync Annotations

Sync Folders

Info Methods

Ping

Backend Ping

Version

Backend Version

Monitor

Navigation

Toolbox

Views

Community Services Journal Annotations Service V1.3

Contents

Overview

Technical Overview

Transport Media Types

Base URL

Annotation Methods

Retrieve Annotations Using Optional Query Parameters

Retrieve Annotations By Id

Retrieve Annotations By Folder Id

Retrieve Annotations Not Associated with a Folder

Create and Update Annotations

Delete Annotations Using Optional Query Parameters

Delete Annotations By ID's

Delete Annotations By ID

Folder Methods

Retrieve Folders Using Optional Query Parameters

Retrieve Folder By Folder Id

Create and Update Multiple Folders

Create a Single Folder

Delete Folders

Delete Folder

Tag Methods

Retrieve Tags

Sync Methods

Sync Annotations

Sync Folders

Info Methods

Ping

Backend Ping

Version

Backend Version

Monitor

Navigation

Toolbox