Search Technologies Assessment · Web viewFor adding a background image you must provided the naId and objectId which contains the actual image on the storage. When adding a background

National Archives and Records Administration

National Archives Catalog (The Catalog)

Authorized User API– Catalog Perspective –

Status-FinalVersion 1.7

September 3, 2015

NARA Catalog Authorized User API

National Archives & Records Administration


Version 1.7

Contract Number GS-35F-0541U

Order Number NAMA-13-F-0120

September 3, 2015

http://www.google.com/url?sa=i&rct=j&q=&esrc=s&frm=1&source=images&cd=&cad=rja&docid=owCr1QpR6RHqlM&tbnid=Nzjz_YVq0miSxM:&ved=0CAUQjRw&url=http://blogs.archives.gov/aotus/?attachment_id=1236&ei=51H6Ub_GHdO64APu34H4Aw&bvm=bv.50165853,d.dmg&psig=AFQjCNEMljwv59HAB11EckpVc6CXxxOUkA&ust=1375445858498456


Contents

1 Overview................................................................................................................21.1 Other Relevant Documents...............................................................................................2

1.2 Relation to API Reference Guide........................................................................................2

2 Account Administrator API.....................................................................................32.1 Creating Accounts..............................................................................................................3

2.2 Searching for Accounts......................................................................................................4

2.3 Fetching User Notes...........................................................................................................7

2.4 Editing User Information....................................................................................................8

3 Moderating Contributions....................................................................................123.1 Viewing the Contributions Stream...................................................................................12

3.1.1 Parameters..............................................................................................................12

3.1.2 Response.................................................................................................................12

3.1.3 Examples.................................................................................................................14

3.1.4 Error Codes.............................................................................................................17

3.2 Fetching an Individual Contribution.................................................................................18

3.3 Fetching Contribution Notes............................................................................................19

3.4 Fetching List of Transcription / Translation Versions.......................................................20

3.5 Fetching a Specific Version..............................................................................................21

3.5.1 Parameters..............................................................................................................23

3.5.2 Response.................................................................................................................23

3.6 Contribution Removal......................................................................................................23

3.6.1 Authorization credentials........................................................................................23

3.6.2 Removing Contributions..........................................................................................24

3.7 Background images..........................................................................................................25

3.7.1 Adding a background image....................................................................................25

3.7.2 Fetching background images...................................................................................27

3.7.3 Deleting background images...................................................................................27

3.7.4 Fetching background images for User Interface......................................................27

3.8 Online Availability header................................................................................................28

3.8.1 Updating the online availability header..................................................................28


3.8.2 Fetching online availability header..........................................................................29

3.8.3 Restoring online availability header........................................................................30

3.8.4 Removing online availability header.......................................................................30


Version Control

Version Date Reviewer Summary Description

0.1 2014-03-04 Paul Nelson Initial Version. Complete account administration section.

0.2 2014-03-08 Paul Nelson First complete version

0.3 2014-03-09 Kristy Martin Internal review

1.0 2104-03-10 Initial Release

1.1 2014-11-14 Brandon Stahl Removed “Confidential to Search Technologies” text from footer

1.2 2014-11-24 Brandon Stahl Replaced https://research.archives.gov url with https://catalog.archives.gov url

1.3 2015-03-17 Luis Vargas Added miscellaneous items for Congressional Fields

1.4 2015-03-26 Luis Vargas Removed miscellaneous items for Congressional Fields

1.5 2015-07-09 Luis Vargas, Alejandro Baltodano, Kristy Martin

Added annotation removal API methodsChanged branding for system name throughout document. Added cover sheetAdded sections 3.7 and 3.8

1.6 2015-08-06 Brandon Stahl Added Invalid_Login error code

1.7 2015-09-03 Alejandro Baltodano

Updated examples

1

https://catalog.archives.gov/

https://research.archives.gov/


1 Overview

This document provides the details of the APIs for handling authorized user requests.

Specifically, this document will cover:

Account Administration API

Moderators API

1.1 Other Relevant DocumentsOther documents relevant to this document:

NARA Catalog User Interface Design

o Identifies all end-user functionality which must be supported by these APIs.

NARA Catalog Architecture Design

o Explains the data model for information in the Catalog.

NARA Catalog API Reference Guide

o Provides all of the APIs for public user.

1.2 Relation to API Reference GuideThis document covers APIs for authorized users. As such, this document is an addendum to the API Reference guide. All information in the original API reference guide in regards to API structure, philosophy, etc. applies to this Authorized User’s API Reference guide.

2


2 Account Administrator API

This section covers APIs for administering accounts which are not already described in the NARA Catalog API Reference Guide.

What’s in this section:

Creating new accounts

Searching for accounts

Specifying a reason and note when deactivating accounts

o Viewing reasons and notes

Resetting passwords

2.1 Creating AccountsUse the following URL for creating accounts:

POST https://catalog.archives.gov/api/v1/users?parameters...

Note:

HTTPS (SSL) protocol is absolutely required whenever modifying account information.

o Standard HTTP requests will be rejected.

Log in is required.

o Only users with “accountAdmin” rights can create accounts.

Note that the POST HTTP Method is required.

Parameters

Parameter Description ExamplesuserType=

standard|power

Specify the user type. If not specified, “standard” is assumed.

userType=power

userType=standard

For use when action=change

rights=moderator,accountAdmin,accountAdminMod

Specify additional rights for the user. This can be either moderator, accountAdmin, or accountAdminMod.

rights=moderator

rights=accountAdmin

email=email Specify the new e-mail address for the user. [email protected]

fullName=full-name Specify the new full name for the user. fullName=Thomas%20Jefferson

3


Parameter Description ExamplesdisplayFullName=

true|falseSet to “true” if the full name for the user should be displayed to the public, “false” otherwise.

displayFullName=true

Examples

Create a new account:

POST https://catalog.archives.gov/api/v1/users?userName=wjefferson&userType=standard &[email protected]&fullName=William Jefferson Clinton&displayFullName=true&password=P@ssword

Response

The response will the standard Catalog response (see the NARA Catalog API Reference Guide for more information).

Error Codes

If the paging parameters are incorrect, then a standard error header will be returned with one of the following error codes:

Error Code Description Parameters

NOT_LOGGED_IN Attempt to view or modify account information without logging in.

none

INSUFFICIENT_RIGHTS Attempted to add an account without account admin rights.

request: The user ID who made the request.

USERNAME_EXISTS Attempted to create an account with a username which already exists.

request: The user ID which already exists.

EMAIL_EXISTS Specified email address already registered to another user.

email: Requested E-mail.currentUser: The user to which the e-mail is already registered.

INVALID_LOGIN Attempt to log in with incorrect credentials.

User; User ID entered.Password: Password entered.

2.2 Searching for AccountsUse the following URL for search for accounts:

GET https://catalog.archives.gov/api/v1/users?parameters...

Note:

HTTPS (SSL) protocol is absolutely required whenever searching account information.


4


Log in is required.

o Only users with “accountAdmin” rights can search accounts.

Parameters

Parameter Description Examplesaction=search Used to distinguish search requests from

other sorts of requests (for future use).action=search

For use when action=change

fieldName=search-string

Specify a field to use to filter the results.The following field names can take partial string values. All records which contain the string anywhere within the name will be returned (case insensitive): id – The registered username for the

user. For example, “kmartin”. fullName – The full name of the user. email – The E-mail address of the user.

The following fields take enumerated values. The entire value must be specified as given: userType – The type of user. Any of

“power”, “standard”, “moderator” or “accountAdmin”.

status – Either “active” or “inactive”.The following field must take an entire ID number. Partial ID numbers are not allowed: internalId – The internal ID number for

the user.

id=martin

id=mar&email=comcast

fullName=george&status=inactive

sort=field [asc|desc] Specify how the results will be sorted. The field can be any of the same fields specified above: “user”, “fullName”, “email”, “userType”, “status” and “userId”.Only a single level of sorting is allowed.

sort=user asc

sort=userType desc

offset=# Specify the starting row number for the results to show. With rows, this can be used to page the results.

offset=0

offset=100

rows=# Specify the number of rows to return in the results.

rows=25

rows=100

Examples

Create a new account:

5


GET https://catalog.archives.gov/api/v1/users?action=search&id=kmar&status=active&sort=id desc&offset=0&rows=25

Response

The response will be returned as a list of <user> tags inside a parent <users> tag. Each user will have the following fields:

internalId – Holds the internal database ID for this user.

id – Holds the username. This is referred to as the “@id” in the standard API Guide, and so “@id” is used here as well.

type – The type of user. Either “standard” or “power”.

rights – Holds a comma-separated list of additional rights for the user. Rights can be either of “moderator”, “accountAdmin”, or both.

fullName – Holds the full name of the user.

email – Holds the E-mail address of the user.

status – Is the status of the user. Either “active” or “inactive”.

hasNotes – “true” if there are additional notes on the user. “false” otherwise.

JSON ExampleGET https://catalog.archives.gov/api/v1/users?action=search&id=jeffers&

sort=id desc&offset=0&rows=25

{ "users":{ “@total”:”2”, “@searchTotal”:”2”, “user”:[ { "internalId":12345, "id":"tjefferson", "type":"standard", "rights”:”regular”, "fullName":"Thomas Jefferson", "email":"[email protected]", "status":"active", "hasNote":true "isNaraStaff”:false, "accountCreatedTs”:”2014-10-12T19:40:21:000Z” }, { "internalId":12348, "id":"gjefferson", "type":"power", "rights”:”moderator”, "fullName":"George Jefferson", "email":"[email protected]", "status":"active", "hasNote":false, "isNaraStaff”:true, "accountCreatedTs”:”2014-05-06T18:45:12:000Z” } ]}

6


XML ExampleGET https://catalog.archives.gov/api/v1/users?action=search&id=jeffers&sort=id

desc&offset=0&rows=25&format=xml

<users searchTotal=”2” total=”2”> <user> <internalId>12345</internalId> <id>tjefferson</id> <type>standard</type> <rights>regular</rights> <fullName>Thomas Jefferson</fullName> <email>[email protected]</email> <displayFullName>false</displayFullName> <status>active</status> <hasNotes>true</hasNotes> <isNaraStaff>false</isNaraStaff> <accountCreatedTs>2014-10-12T19:40:21:000Z</accountCreatedTs> </user> <user> <internalId>12348</internalId> <id>gjefferson</id> <type>power</type> <rights>moderator</rights> <fullName>George Jefferson</fullName> <email>[email protected]</email> <status>active</status> <hasNotes>false</hasNotes> <isNaraStaff>true</isNaraStaff> <accountCreatedTs>2014-05-06T18:45:12:000Z</accountCreatedTs> </user></users>

Error Codes




none

INSUFFICIENT_RIGHTS Attempted to add an account without account admin rights.


INVALID_PARAM_VALUE The value specified to a parameter was invalid. For example, a bad field name, negative number for offset, etc.

param: The parameter which contained the invalid value.



2.3 Fetching User NotesUser notes can be fetched with the following URL:

GET https://catalog.archives.gov/api/v1/users/<user-id>/notes

7


Note:

HTTPS (SSL) protocol is absolutely required whenever searching account information.


Log in is required.

o Only users with “accountAdmin” rights can fetch user notes.

Response

The response will be returned as a single <user> tag with nested <note> tags. For each <note> tag, there will be the following fields:

@adminId – The user ID of the account administrator who added the note.

@action – The action performed. Can be any of “activate”, “deactivate” or “edit”.

@when – The date time when the note was created and the action performed.

@reason – A textual reason for the note.

@reasonId – An identifier for the associated reason.

The textual note will be specified as the content of the <note> tag.

JSON ExampleGET https://catalog.archives.gov/api/v1/users/kmartin/notes

"user":{ "@id":"tjefferson", "note":[ { "@adminId":"kmartin", "@action":"activate", "@when":"2014-03-04T21:17:32", "@reason":"User Request", "@reasonId":"4","$":"Turns out user was faithfully copying the text of an advertisement" }, { "@adminId":"gjefferson", "@action":"deactivate", "@when":"2014-03-01T10:04:03", "@reason":"Spam Account", "@reasonId":"2","$":"User appears to be spamming the system" } ]}

XML ExampleGET https://catalog.archives.gov/api/v1/users/kmartin/notes?format=xml

<user id="tjefferson"> <note adminId="kmartin" action="activate" when="2014-03-04T21:17:32" reason="User Request" reasonId="4"> Turns out user was faithfully copying the text of an advertisement </note> <note adminId="gjefferson" action="deactivate" when="2014-03-01T10:04:03" reason="Spam Account" reasonId="2">

8


User appears to be spamming the system </note></user>

2.4 Editing User InformationAccount information can be viewed and modified using the following URL:

PUT https://catalog.archives.gov/api/v1/users/<user-id>/accounts?parameters...

Note:

HTTPS (SSL) protocol is absolutely required whenever modifying account information.


The user must be logged in.

The user must have account administrator privledges.

Parameters

Parameter Description Examplesaction=

adminChangeIdentifies what administrative change to make to the user’s account. adminChange – Change the user’s

account information. When specified, used any of the parameters below to change the specified information.

action=adminChange

userType=standard|power

Specify the new user type. Generally, power users have fewer limits on resource usage than standard users.

type=standard

type=power

rights=regular|moderator|accountAdmin|accountAdminMod

Specify the access rights for the user. moderator – Can can view streams of

new annotations created by users and can delete annotations.

accountAdmin – Can create, search, and modify user accounts.

rights=accountAdmin

rights=moderator

email=email Specify the new e-mail address for the user. [email protected]

fullName=full-name Specify the new full name for the user. fullName=Thomas%20Jefferson

displayFullName=true|false

Set to “true” if the full name for the user should be displayed to the public, “false” otherwise.

displayFullName=true

status=active|inactive

Specify the new status for the user. status=active

status=inactive

9


Parameter Description ExamplesreasonId=# Specify the ID number of the reason to be

saved with the edit.See section Error: Reference source not found for more information on fetching lists of reasons. Only required if the action is to deactivate the user.

reason=32

notes=Note text... Specify text of a note to store with the account.

notes=Deactivated due to spamming by user.

Notes:

When action=adminChange, only values which are specified in the parameters will be changed. All other values will remain the same.

There should be no other parameters when action=resetPassword.

reasonId and note are required when status=inactive.

Examples

Change the tjefferson’s E-mail:

PUT https://catalog.archives.gov/api/v1/users/tjefferson/accounts?action=adminChange&type=power&[email protected]

Deactivate tjefferson:

PUT https://catalog.archives.gov/api/v1/users/tjefferson/accounts?action=adminChange&status=inactive&reasonId=2&note=Account is obviously face. Everyone knows that Thomas Jefferson prefers using a quill instead of a computer.

Reset tjefferson’s password:

PUT https://catalog.archives.gov/api/v1/users/tjefferson/accounts?action=resetPassword

Response

The response will the standard Catalog response (see the NARA Catalog API Reference Guide for more information). In addition, the response will also contain the E-mail address, user-id, and full name of the user whose information was changed:

JSON ExamplePUT https://catalog.archives.gov/api/v1/users/tjefferson/account?action=resetPassword

{ "header":{ "@status":"200", "@time":"2014-05-31T16:15:47.715Z", "request":{ "@path":"/api/v1/users/tjefferson/account", "action":"resetPassword"

10


} }, "user":”success”}

XML ExamplePUT https://catalog.archives.gov/api/v1/users/tjefferson/account?action=resetPassword&format=xml

<opa-response><header status="200" time="2014-05-31T16:15:47.715Z">

<request path="/api/v1/users/tjefferson/account"><action>resetPassword</action>

</request></header>

<user>success</></opa-response>

Error Codes




none

NOT_OWNER Attempt to modify the account information for other users.


MISSING_NOTE Notes are required when an account is deactivated.

none

MISSING_REASON A reason code is required when an account is deactivated.

none



11


3 Moderating Contributions

This section covers the methods available for moderators to moderate the stream of contributions.

3.1 Viewing the Contributions StreamAll user contributions are viewable as a stream of updates, using the following URL:

GET http://catalog.archives.gov/api/v1/moderator/stream?parameters...

Note:


The user must have moderator privledges.

3.1.1 Parameters

All of the user contribution methods support several common parameters for paging and sorting.

Parameter Description Examplesoffset=# The zero-based offset into the list of the

first result to be returned. This parameter is used in combination with ‘rows’ to paginate the list. If missing, the default offset is 0.If an offset less than 0 an error is returned.

offset=100

rows=# Indicates the number of entries in the list to fetch. The default is 25.

rows=50

filterType=TG|CM|TR|Moderator

Specify what items to show in the stream. filterType=TG

filterType=Moderator

naId=<naid> Specify an NAID to filter the results. naId=7229324

3.1.2 Response

The contributions in the stream will be returned as a list of nested <contribution> tags inside of a <contributionsTag> stream.

The following are the elements in the <contributionsStream> tag:

offset – The (zero based) number of the first contribution in the list.

rows – The number of contributions returned in this transaction.

12


contribution – parent tag which holds all information about each contribution.

o @transId – The transaction ID for the contribution.

o @type – The type of contribution.

One of “comment”, “reply”, “tag”, “transacription” or “translation”.

o @on – Identifies what in the Catalog system was annotated.

One of “person”, “organization”, “description”, or “object”.

o @when – Specifies the date and time when the contribution occurred.

o @userId – Specifies the account ID (username) of the user who was responsible for the contribution.

o @fullName – The full name of the user.

o @isNaraStaff – “true” if the user is a NARA staff member.

o @authorUserId – Specifies the account ID (username) of the user who created the contribution.

o @authorFullName – The full name of the user who created the contribution.

o @authorDisplayFullName – “true” if the author’s fullname should be displayed.

o @authorIsNaraStaff – “true” if the author is a NARA staff member.

o @action – The action associated with this contribution.

Can be one of “new”, “update”, “remove”, or “restore”.

o @hasNote – “true” if there are moderator notes associated with the contribution.

o @notes – Notes added after an action was performed.

o @reason – Reason specified after an action was performed.

o title – A display title for the contribution. Usually the title of the associated description or authority record.

o accessPath – The API path for accessing the item to which the contribution was attached.

o comment – Parent tag, included if @type=”comment”.

@id – The ID for this comment.

text – The text of the comment.

o reply – Parent tag, included if @type=”reply”.

@id – The ID of the reply.

@commentId – The ID of the comment which contains the reply.

text – The text of the reply.

o tag – Parent tag, included if @type=”tag”.

13


text – The text of the tag.

o transcription – Parent tag, included if @type=”transcription”.

teaser – Holds “teaser text” for the transcription, the first 200 characters or so of the transcription.

o translation – Parent tag, included if @type=”translation”.

@code – Specifies the ISO-936-3 (three letter) language code for the language of the translation.

teaser – Holds “teaser text” for the translation, the first 200 characters or so.

o description – Parent tag, included if @on=”description”.

@naid – The NAID of the description on which the comment was made.

o object – Parent tag, included if @on=”object”.

@naid – The NAID of the description which contains the object.

@id – The object ID on which the comment was made.

@display – A display value which helps identify the object to the user. Typically a page number.

o person – Parent tag, included if @on=”person”.

@id – The person ID number.

o organization – Parent tag, included if @on=”organization”.

@id – The organization ID number.

3.1.3 Examples

JSON ExampleGET http://catalog.archives.gov/api/v1/moderator/stream?filterType=Moderator&offset=0&rows=6

{ "@offset":"0", "@rows":"6", "contribution":[ { "@transId":"194238", "@type":"comment", "@on":"object", "@when":"2014-07-21T16:22:58", "@userId":"tjefferson", "@fullName":"Thomas Jefferson", "@isNaraStaff":"true", "@hasNote":"true", "@action":"new", "comment":{ "@id":"15239", "text":"What's the importance of Sterling engine?!" }, "title":"Spring 1981: Harry S. Truman on CIA Covert Operations, by Hayden B. Peake ", "accessPath":"holdings/7283080/objects/263/annotations/comments/15239", "object":{ "@naid":"7283080",

14


"@id":"263", "@display":"2/11" } }, { "@transId":"194237", "@type":"reply", "@on":"description", "@when":"2014-06-21T16:22:58", "@userId":"gjefferson", "@fullName":"George Jefferson", "@hasNote":"false", "@action":"new", "reply":{ "@id":"72523", "@commentId":"14200", "text":"The dates are misleading. Even though the investigation was not completed, it is

still marked as completion." }, "title":"Fall 1981: 8-91-1 An Interview with Richard Helms, by David Frost", "accessPath":"holdings/7283099/annotations/comments/14200/72523", "description":{ "@naid":"7283099" } }, { "@transId":"194236", "@on":"person", "@when":"2014-06-21T12:15:03", "@userId":"kmartin", "@hasNote":"false", "@action":"update", "comment":{ "@id":"8889", "text":"What does the 'S' stand for? Anyone know?" }, "title":"Truman, Harry S., 1884-1972 ", "accessPath":"authorities/people/1307945/annotations/comments/8889", "person":{ "@id":"1307945" } }, { "@transId":"194235", "@type":"transcription", "@on":"object", "@when":"2014-07-20T08:44:31", "@userId":"tjefferson", "@fullName":"Thomas Jefferson", "@isNaraStaff":"true", "@hasNote":"true", "@action":"delete", "transcription":{ "teaser":"This public information film was funded by the Office of Education. Deaf

education is the education of students with various hearing levels in a way that addresses the students' individual differences and needs. Ideally, this process involves the individually planned and systematically monitored arrangement of teaching procedures, adapted equipment and materials, accessible settings..."

}, "title":"TEACHING SPEECH TO THE PROFOUNDLY DEAF: THE SPEECH KIT 1,2,3", "accessPath":"holdings/1319/objects/1/annotations/transcription", "object":{ "@naid":"1319", "@id":"1", "@display":"1/1" } }, { "@transId":"194234", "@type":"tag", "@on":"description", "@when":"2014-06-20T07:29:55",

15


"@userId":"gjefferson", "@fullName":"George Jefferson", "@hasNote":"false", "@action":"new", "tag":{ "@text":"Hearing Impared" }, "title":"Pittsburgh, [Pennsylvania] - 157-19-v.4 [Classification - Civil Unrest] -- Various

Racial Matters", "accessPath":"authorities/people/5541655/annotations/tags/Hearing%20Impared", "description":{ "@naid":"5541655" } }, { "@transId":"194235", "@type":"translation", "@on":"object", "@when":"2014-07-20T08:44:31", "@userId":"tjefferson", "@fullName":"Thomas Jefferson", "@isNaraStaff":"true", "@hasNote":"true", "@action":"restore", "translation":{ "@code":"ita", "teaser":"FILM PROMOZIONALE: INCORAGGIA INDIVIDUALI E DI GRUPPO attivitá nella Comunitá

che sará di aiuto nel miglioramento dell'ambiente. SPETTACOLI PROGETTI essere esercitate TAMPA, ATLANTA, SAN FRANCISCO, e altre aree. I progetti spaziano dalla figli che studiano l'ambiente da BARCHE palude, AGLI STUDENTI scavando in una baia, E DI UNA RAGAZZA CHE CATTURA LETTURE DECIBEL metri nel centro della cittá ........"

}, "title":"Environmental Education -- A Beginning", "accessPath":"holdings/1256/objects/1/annotations/translations/ita", "object":{ "@naid":"1256", "@id":"1", "@display":"Segment 1/2" } } ]}

XML ExampleGET

http://catalog.archives.gov/api/v1/moderator/stream?filterType=Moderator&offset=0&rows=6&format=xml

<contributionsStream offset="0" rows="6"> <contribution transId="194238" type="comment" on="object" when="2014-07-21T16:22:58" userId="tjefferson" fullName="Thomas Jefferson" isNaraStaff="true" hasNote="true" action="new"> <comment id="15239"> <text>What's the importance of Sterling engine?!</text> </comment> <title>Spring 1981: Harry S. Truman on CIA Covert Operations, by Hayden B. Peake </title> <accessPath>holdings/7283080/objects/263/annotations/comments/15239</accessPath> <object naid="7283080" id="263" display="2/11"/> </contribution>

<contribution transId="194237" type="reply" on="description" when="2014-06-21T16:22:58" userId="gjefferson" fullName="George Jefferson" hasNote="false" action="new"> <reply id="72523" commentId="14200"> <text>The dates are misleading. Even though the investigation was not completed, it is still

marked as completion.</text> </reply> <title>Fall 1981: 8-91-1 An Interview with Richard Helms, by David Frost</title>

16


<accessPath>holdings/7283099/annotations/comments/14200/72523</accessPath> <description naid="7283099"/> </contribution>

<contribution transId="194236" on="person" when="2014-06-21T12:15:03" userId="kmartin" hasNote="false" action="update"> <comment id="8889"> <text>What does the 'S' stand for? Anyone know?</text> </comment> <title>Truman, Harry S., 1884-1972 </title> <accessPath>authorities/people/1307945/annotations/comments/8889</accessPath> <person id="1307945"/> </contribution>

<contribution transId="194235" type="transcription" on="object" when="2014-07-20T08:44:31" userId="tjefferson" fullName="Thomas Jefferson" isNaraStaff="true" hasNote="true" action="delete"> <transcription> <teaser>This public information film was funded by the Office of Education. Deaf education

is the education of students with various hearing levels in a way that addresses the students' individual differences and needs. Ideally, this process involves the individually planned and systematically monitored arrangement of teaching procedures, adapted equipment and materials, accessible settings...</teaser>

</transcription> <title>TEACHING SPEECH TO THE PROFOUNDLY DEAF: THE SPEECH KIT 1,2,3</title> <accessPath>holdings/1319/objects/1/annotations/transcription</accessPath> <object naid="1319" id="1" display="1/1"/> </contribution>

<contribution transId="194234" type="tag" on="description" when="2014-06-20T07:29:55" userId="gjefferson" fullName="George Jefferson" hasNote="false" action="new"> <tag text="Hearing Impared"/> <title>Pittsburgh, [Pennsylvania] - 157-19-v.4 [Classification - Civil Unrest] -- Various

Racial Matters</title> <accessPath>authorities/people/5541655/annotations/tags/Hearing%20Impared</accessPath> <description naid="5541655"/> </contribution>

<contribution transId="194235" type="translation" on="object" when="2014-07-20T08:44:31" userId="tjefferson" fullName="Thomas Jefferson" isNaraStaff="true" hasNote="true" action="restore"> <translation code="ita"> <teaser>FILM PROMOZIONALE: INCORAGGIA INDIVIDUALI E DI GRUPPO attività nella Comunità che

sarà di aiuto nel miglioramento dell'ambiente. SPETTACOLI PROGETTI essere esercitate TAMPA, ATLANTA, SAN FRANCISCO, e altre aree. I progetti spaziano dalla figli che studiano l'ambiente da BARCHE palude, AGLI STUDENTI scavando in una baia, E DI UNA RAGAZZA CHE CATTURA LETTURE DECIBEL metri nel centro della città ........</teaser>

</translation> <title>Environmental Education -- A Beginning</title> <accessPath>holdings/1256/objects/1/annotations/translations/ita</accessPath> <object naid="1256" id="1" display="Segment 1/2"/> </contribution>

</contributionsStream>

3.1.4 Error Codes

If the paging parameters are incorrect, then a standard error header will be returned (see section Error: Reference source not found) with one of the following error codes:


INVALID_OFFSET An incorrect offset was requested. offset: The requested offset.

17


avail: The number of rows available.

INVALID_ROWS A “rows” number less than zero was requested.

rows: The requested rows.

TOO_MANY_ROWS Too many rows were requested. rows: The requested rows.max: The maximum number of rows allowed.

INVALID_SORT Invalid sort field or sort direction requested. none

3.2 Fetching an Individual ContributionAll user contributions are viewable as a stream of updates, using the following URL:

GET http://catalog.archives.gov/api/v1/moderator/tags/89132

Note:



The data returned will be the same as described in section 3.1.2. If the ID does not exist, a 404 error will be returned.

JSON ExampleGET http://catalog.archives.gov/api/v1/users/moderator/tags/194238?offset=0&rows=6

{ "@transId":"194238", "@type":"comment", "@on":"object", "@when":"2014-07-21T16:22:58", "@userId":"tjefferson", "@fullName":"Thomas Jefferson", "@isNaraStaff":"true", "@hasNote":"true", "@action":"new", "comment":{ "@id":"15239", "text":"What's the importance of Sterling engine?!" }, "title":"Spring 1981: Harry S. Truman on CIA Covert Operations, by Hayden B. Peake ", "object":{ "@naid":"7283080", "@id":"263", "@display":"2/11" }}

XML ExampleGET http://catalog.archives.gov/api/v1/moderator/tags/194238?offset=0&rows=6&format=xml

<contribution transId="194238" type="comment" on="object" when="2014-07-21T16:22:58" userId="tjefferson" fullName="Thomas Jefferson" isNaraStaff="true" hasNote="true" action="new"> <comment id="15239">

18


<text>What's the importance of Sterling engine?!</text> </comment> <title>Spring 1981: Harry S. Truman on CIA Covert Operations, by Hayden B. Peake </title> <object naid="7283080" id="263" display="2/11"/></contribution>

3.3 Fetching Contribution NotesAll contributions from the contributions stream, can be deleted or restored using the following URL:

GET http://catalog.archives.gov/api/v1/moderator/<contribution-id>/notes

Note:



Response

The response will contain a <notes> tag with a list of embedded <note> tags. Within the <notes> tag are the following elements:

@contributionId – The identifier of the contribution from the contribution stream to which the notes are attached.

@total – The total number of notes returned.

note – Parent tag which contains all information about one note. The content of the tag contains the text of the note. Also contains the following sub elements:

o @adminId – Holds the moderator ID which made the change.

o @action – Holds the action made by the moderator.

One of “remove” or “restore”.

o @when – Holds the date the note was created.

o @reason – Holds the textual version of the reason code.

o @reasonId – Holds the ID version of the reason code.

JSON ExampleGET http://catalog.archives.gov/api/v1/users/moderator/194238/notes?offset=0&rows=6

{ "@contributionId":"194238", "@total":"2", "note":[ { "@adminId":"kmartin", "@action":"restore", "@when":"2014-03-04T21:17:32", "@reason":"User Request", "@reasonId":"4","$":"\n Turns out user was faithfully copying the text of an

advertisement\n "

19


}, { "@adminId":"gjefferson", "@action":"remove", "@when":"2014-03-01T10:04:03", "@reason":"Spam", "@reasonId":"2","$":"\n User appears to be spamming the system\n " } ]}

XML ExampleGET http://catalog.archives.gov/api/v1/moderator/194238/notes?offset=0&rows=6&format=xml

<notes contributionId="194238" total="2"> <note adminId="kmartin" action="restore" when="2014-03-04T21:17:32" reason="User Request" reasonId="4"> Turns out user was faithfully copying the text of an advertisement </note> <note adminId="gjefferson" action="remove" when="2014-03-01T10:04:03" reason="Spam" reasonId="2"> User appears to be spamming the system </note></notes>

3.4 Fetching List of Transcription / Translation VersionsTranscriptions – list of versions:

GET http://catalog.archives.gov/api/v1/moderator/transcriptions/id/{naid}/objects/{obj-id}

Translations – list of versions:

GET http://catalog.archives.gov/api/v1/moderator/translations/id/{naid}/objects/{obj-id}?language=<language>

Note:



Response

Versions are always returned sorted in reverse time order (youngest first).

The result will be a <versions> tag which contains the following:

@naid – The NAID of the description to which the translation/transcription is attached.

@objectId – The object identifier to which the transcription / translation is attached.

@type – The type of annotation.

o Either “transcription” or “translation”.

@code – The languge code of the translation.

20


version – Parent tag which contains information about a specific version. Contains the following sub-elements:

o @num – The version number. An incrementing number from 1 (first version) to N (last version).

o @action – What happened to cause the version. One of “save”, “remove” or “restore”.

o @when – The date-time when the version was created.

JSON ExampleGET http://catalog.archives.gov/api/v1/moderator/transcriptions/id/72254132/objects/3

{ "@naid":"72254132", "@objectId":"3", "@type":"transcription", "version":[ { "@num":"3", "@action":"restore", "@when":"2014-03-07T18:45:46" }, { "@num":"2", "@action":"remove", "@when":"2014-03-06T08:15:16" }, { "@num":"1", "@action":"save", "@when":"2014-03-02T11:17:21" } ]}

XML ExampleGET http://catalog.archives.gov/api/v1/moderator/transcriptions/id/72254132/objects/3?format=xml

<versions naid="72254132" objectId="3" type="transcription"> <version num="3" action="restore" when="2014-03-07T18:45:46"/> <version num="2" action="remove" when="2014-03-06T08:15:16"/> <version num="1" action="save" when="2014-03-02T11:17:21"/></versions>

3.5 Fetching a Specific VersionUse the following URLs to fetch a specific version of a transcription or translation.

Transcriptions – specific version:

GET http://catalog.archives.gov/api/v1/moderator/transcriptions/id/{naid}/objects/{obj-id}?version={version-number}

Translations – specific version:

21


GET http://catalog.archives.gov/api/v1/moderator/translations/id/{naid}/objects/{obj-id}?language={language}&version={version-number}

Response

The response will be the same as specified in section 4.5.1 (API Reference Guide) for transcriptions and 4.6.1 (API Reference Guide) for translations.

3.6 Deleting and Restoring Contributions.All contributions from the contributions stream, can be deleted or restored using the following URL:

Deleting and restoring comments:

DELETE http://catalog.archives.gov/api/v1/moderator/comments/id/{naid}/{comment-id}?notes=note text. . .&reasonId=#

PUT http://catalog.archives.gov/api/v1/moderator/comments/id/{naid}/{comment-id}?notes=note text. . .&reasonId=#

Deleting and restoring replies:

DELETE http://catalog.archives.gov/api/v1/moderator/comments/id/{naid}/{comment-id}?notes=note text. . .&reasonId=#

PUT http://catalog.archives.gov/api/v1/moderator/comments/id/{naid}/{comment-id}?notes=note text.. .&reasonId=#

Deleting and restoring transcriptions:

DELETE http://catalog.archives.gov/api/v1/moderator/transcriptions/id/{naid}/objects/{obj-id}?notes=note text. . .&reasonId=#&versionNumber={version}

PUT http://catalog.archives.gov/api/v1/moderator/transcriptions/id/{naid}/objects/{obj-id}?versionNumber={version-number}&notes=note text. . .&reasonId=#&versionNumber={version}

Deleting and restoring translations:

DELETE http://catalog.archives.gov/api/v1/moderator/translations/id/{naid}/objects/{obj-id}?language={lang-code}&notes=note text. . .&reasonId=#&versionNumber={version}

PUT http://catalog.archives.gov/api/v1/moderator/translations/id/{naid}/objects/{obj-id}?language={lang-code}&versionNumber={version-number}&notes=note text. . .&reasonId=#&versionNumber={version}

Note:



22


3.6.1 Parameters

All of the user contribution methods support several common parameters for paging and sorting.

Parameter Description Examplesaction=

moderatorRestore|moderatorRemove

Specify that this is a moderator restore or remove action, instead of an end-user modify action.

action=restore

notes=note text. . . Specify a textual note to save with the action.

notes=Obviously spam

reasonId=# The reason number for the change. reason=6

Examples

DELETE

http://catalog.archives.gov/api/v1/moderator/comments/id/722894/12345?notes=Appears to be spam&reasonId=4

PUT

http://catalog.archives.gov/api/v1/moderator/comments/id/7228942/comments/12345?notes=Mistook unusual middle name for spam&reasonId=6

DELETE

http://catalog.archives.gov/api/v1/moderator/transcriptions/id/7228392/objects/3?notes=Contains foul language&reasonId=4

PUT

http://catalog.archives.gov/api/v1/moderator/transcriptions/id/7228392/objects/3?versionNumber={version-number}&notes=Mistaken removal&reasonId=7

3.6.2 Response

A standard Catalog response will be returned (either success or failure).

3.7 Contribution RemovalAPI provides methods to remove contributions by a moderator user.

3.7.1 Authorization credentials

Just like with adding annotations, using the moderator API requires the Authorization http header with the credentials code that is received in the login response:

23


"opaResponse":{ "header":{ "@status":"200", "time":"2015-06-04T14:43:53.583Z", "request":{ "@path":"\/api\/v1\/login", "action":"login", "userName":"accountadminmod", "format":"json", "pretty":true } }, "credentials":"6B544888D2C7AB44389970C1DD91A1D6.pa01", "user":{ "internalId":1,

The header in the moderator API calls is specified like this:

Authorization: “<credentials code>”

3.7.2 Removing Contributions

Contributions are removed by the moderator using the DELETE Http method.

3.7.2.1 Comments

As a moderator, use the following requests to remove a comment:

DELETE

https://catalog.archives.gov/OpaAPI/api/v1/moderator/comments/id/{naId}/{annotationId}?reasonId=<reason id>

DELETE https://catalog.archives.gov/OpaAPI/api/v1/moderator/comments/id/{naId}/objects/{objectId}/{annotationId}?reasonId=<reason id>

3.7.2.2 Tags

As a moderator, use the following requests to remove a tag:

DELETE https://catalog.archives.gov/OpaAPI/api/v1/moderator/tags/id/{naId}?text={tag text}&reasonId={reason id}

DELETE https://catalog.archives.gov/OpaAPI/api/v1/moderator/tags/id/{naId}/objects/{objectId}/{annotationId}?reasonId={reason id}&text={tag text}

24


3.7.2.3 Transcriptions

As a moderator, use the following request to remove a transcription:

DELETE https://catalog.archives.gov/OpaAPI/api/v1/moderator/transcriptions/id/{naId}/objects/{objectId}?reasonId={reason id}&versionNumber={version number}

Moderartos can perform some tasks associated with the User Interface. These tasks are described in this section.

3.8 Background imagesNARA Catalog home page displays an image as background for the web page. The number of images which can be used as background images can be variable. These specific images are configurable by a moderator user in an easy and straight-forward manner without the need for code changes. Images are part of the Catalog storage and they can be referenced by a valid naId and objectId pointing to the image itself.

Images are randomly selected from the configured set of images every time that the catalog’s home page is loaded.

Operations for background images can be executed using the following URLs:

Add a background image:

POST https://catalog.archives.gov/iapi/v1/moderator/background-image?naId=<NAID>&objectId=<objectId>

Fetch the list of configured images in Catalog:

GET https://catalog.archives.gov/iapi/v1/moderator/background-image

Users can fetch a specific image providing the naId and objectId of the image:

GET https://catalog.archives.gov/iapi/v1/moderator/background-image&naId=<NAID>&objectId=<objectId>

Delete a background image from Catalog:

DELETE https://catalog.archives.gov/iapi/v1/moderator/background-image?naId=<NAID>&objectId=<objectId>

3.8.1 Adding a background image

Use the following URL to add a background image:

GET https://catalog.archives.gov/iapi/v1/moderator/background-image?naId=<NAID>&objectId=<objectId>

25


For adding a background image you must provided the naId and objectId which contains the actual image on the storage.

When adding a background image, Catalog API will use a third-party service called tinify which will shrink the image, so web pages can be load faster by the browser. The credentials for using this third-party tool can be configurable on the application.properties files as shown below:

tinyfyAPIKey=IcGvopWv-3zBOnN3RiUNN0D4631fmAgptinyfyLocation=shrink-images/

tinifyAPIKey: This is the API key generated by the third party for accesing their API with a registered account.

tinifyLocation: This is the folder on S3 where the images were uploaded after shrinking process.

Response

In the download output, the following attributes are provided for each background image:

background-image– Contains information on each background image.

background-image/@naId – The NAID of the description that contains the background image.

background-image/@objectId – The object ID of thebackground image.

background-image/@title – A display title for the contribution. Usually the title of the associated description.

background-image/@path– Cloudfront URL for the shrink image set as background image.

XML ExampleGET https://catalog.archives.gov/iapi/v1/background-image?naId=1667921&objectId=14721075

<background-image naId="1667921" objectId="14721075" title="Photograph of Richard M. Nixon Shaking Hands with Entertainer Elvis Presley in the Oval Office" path="https://d2inpltj4xe04b.cloudfront.net/shrink-images/1667921-5598_2004_a.jpg">

</background-image>

JSON ExampleGET https://catalog.archives.gov/iapi/v1/background-image?naId=1667921&objectId=14721075?

format=json

"background-image":{ "@naId":"1667921", "@objectId":"14721075", "@title":"Photograph of Richard M. Nixon Shaking Hands with Entertainer Elvis Presley in the

Oval Office", "@path":"https:\/\/d2inpltj4xe04b.cloudfront.net\/shrink-images\/1667921-5598_2004_a.jpg" }

26


3.8.1.1 Error Codes

The following error codes are currently defined as part of the API response:


BACKGROUND_IMAGE_NOT_FOUND An invalid or non-existing object was used in the request.

none

A default background image exists and cannot be deleted, although it is displayed only when no other images have been configured for the set. These default background images can be configurable on the applications.properties file as shown below:

defaultBackgroundImages=4958425/14093563;6421795/13087218

Default background images should be separated by semi-colon character, and the format should be naId/objectId.

3.8.2 Fetching background images

A list of configured images in Catalog can be retrieved using the following URL:

GET https://catalog.archives.gov/iapi/v1/moderator/background-image

Users can fetch a specific image providing the naId and objectId of the image:

GET https://catalog.archives.gov/iapi/v1/moderator/background-image&naId=<NAID>&objectId=<objectId>

For example:

GET https://catalog.archives.gov/iapi/v1/moderator/background-image&naId=1667921&objectId=14721075

3.8.3 Deleting background images

Background images can be deleted from Catalog using the following URL:

DELETE https://catalog.archives.gov/iapi/v1/moderator/background-image?naId=<NAID>&objectId=<objectId>

For example:

DELETE https://catalog.archives.gov/iapi/v1/moderator/background-image&naId=1667921&objectId=14721075

3.8.4 Fetching background images for User Interface

Background images can be retrieved by the User Interface using the following URL:

GET https://catalog.archives.gov/iapi/v1/background-image?naId=<NAID>&objectId=<objectId>

27


For example:

GET https://catalog.archives.gov/iapi/v1/background-image&naId=1667921&objectId=14721075

3.9 Online Availability headerThe system shall provide the capability for a Moderator to remove the online availability notification on the full results display of a selected Archival Description as specified in section 7 of the Archival Descriptions Data Model Design document.

Operations for online availability can be executed using the following URLs:

Fetch the online availability header for a description:

GET https://catalog.archives.gov/iapi/v1/moderator/online-availability/<naId>

Update the online availability header for a description:

POST https://catalog.archives.gov/iapi/v1/moderator/online-availability/<naId>?header=<header>

Restore the online availability header for a description:

PUT https://catalog.archives.gov/iapi/v1/moderator/online-availability/<naId>

Delete the online availability header for a description:

DELETE https://catalog.archives.gov/iapi/v1/moderator/online-availability/<naId>

3.9.1 Updating the online availability header

Use the following URL to update the online availability header for a description:

POST https://catalog.archives.gov/iapi/v1/moderator/online-availability/<naId>?header=<header>

Response

In the download output, the following attributes are provided for each description availability header:

online-availability-header– Contains information on each background image.

online-availability-header/@naId – The NAID of the description.

online-availability-header/@title – A display title for the contribution. Usually the title of the associated description.

online-availability-header/@header – Markup text containing the header that will be displayed for the description.

online-availability-header/@enabled – true if header should be displayed, false otherwise.

28


online-availability-header/@timestamp – Date and time of last modification done to this description.

online-availability-header/@actions – Actions peformed over this description.

XML ExampleGET https://catalog.archives.gov/iapi/v1/moderator/online-availability/2268076?parameters...

<online-availability-header naId="2268076" title="Harry S. Truman Files" header="<div> <span style="font-family: sans-serif;"> <b> <span style="color: rgb(178, 178, 0);">This Series contains records, some

of which may not be available online.</span> </b> </span> </div> <div>To obtain a copy or view the records, please contact or visit the National

Archives and Records Administration location(s) listed in the Contact information below. </div>" enabled="true" timestamp="2015-06-30 21:28:00.0">

<actions userId="accountadminmod" fullName="Nara-Admin-Mod" displayFullName="true" isNaraStaff="false" action="UPDATE" actionTS="2015-06-30 21:28:00.0">

</actions></online-availability-header>

JSON ExampleGET https://catalog.archives.gov/iapi/v1/online-availability/2268076?parameters...&format=json

"online-availability-header":{ "@naId":"2268076", "@title":"Harry S. Truman Files", "@header":"<div><span style=\"font-family: sans-serif;\"><b><span style=\"color: rgb(178,

178, 0);\">This Series contains records, some of which may not be available online.<\/span><\/b><\/span><\/div><div>To obtain a copy or view the records, please contact or visit the National Archives and Records Administration location(s) listed in the Contact information below. <\/div>",

"@enabled":"true", "@timestamp":"2015-06-30 21:28:00.0", "actions":[ { "@userId":"accountadminmod", "@fullName":"Nara-Admin-Mod", "@displayFullName":"true", "@isNaraStaff":"false", "@action":"UPDATE", "@actionTS":"2015-06-30 21:28:00.0" } ] }

3.9.1.1 Error Codes

The following error codes are currently defined as part of the API response:


INVALID_ID_VALUE An invalid or non-existing naId was entered.

none

ONLINE_AVALIABILITY_HEADER_NOT_FOUND Online availability header not found for the description.

none

29


3.9.2 Fetching online availability header

The online availability header for a description can be retrieved using the following URL:

GET https://catalog.archives.gov/iapi/v1/moderator/online-availability/<naId>

For example:

GET https://catalog.archives.gov/iapi/v1/moderator/online-availability/2268076

3.9.3 Restoring online availability header

The online availability header for a description can be restored using the following URL:

PUT https://catalog.archives.gov/iapi/v1/moderator/online-availability/<naId>

For example:

PUT https://catalog.archives.gov/iapi/v1/moderator/online-availability/2268076

3.9.4 Removing online availability header

The online availability header for a description can be removed using the following URL:

DELETE https://catalog.archives.gov/iapi/v1/moderator/online-availability/<naId>

For example:

DELETE https://catalog.archives.gov/iapi/v1/online-availability/2268076

30