search technologies assessment · web viewfor adding a background image you must provided the naid...
TRANSCRIPT
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
NARA Catalog Authorized User API
Version 1.7
Contract Number GS-35F-0541U
Order Number NAMA-13-F-0120
September 3, 2015
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
3.8.2 Fetching online availability header..........................................................................29
3.8.3 Restoring online availability header........................................................................30
3.8.4 Removing online availability header.......................................................................30
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
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.
o Standard HTTP requests will be rejected.
4
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
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
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.
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.
INVALID_LOGIN Attempt to log in with incorrect credentials.
User; User ID entered.Password: Password entered.
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
NARA Catalog Authorized User API
Note:
HTTPS (SSL) protocol is absolutely required whenever searching account information.
o Standard HTTP requests will be rejected.
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
NARA Catalog Authorized User API
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.
o Standard HTTP requests will be rejected.
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
NARA Catalog Authorized User API
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¬e=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
NARA Catalog Authorized User API
} }, "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
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
NOT_OWNER Attempt to modify the account information for other users.
request: The user ID who made the request.
MISSING_NOTE Notes are required when an account is deactivated.
none
MISSING_REASON A reason code is required when an account is deactivated.
none
INVALID_LOGIN Attempt to log in with incorrect credentials.
User; User ID entered.Password: Password entered.
11
NARA Catalog Authorized User API
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 be logged in.
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
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
"@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
NARA Catalog Authorized User API
"@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
NARA Catalog Authorized User API
<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:
Error Code Description Parameters
INVALID_OFFSET An incorrect offset was requested. offset: The requested offset.
17
NARA Catalog Authorized User API
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 user must be logged in.
The user must have moderator privledges.
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
NARA Catalog Authorized User API
<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:
The user must be logged in.
The user must have moderator privledges.
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
NARA Catalog Authorized User API
}, { "@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:
The user must be logged in.
The user must have moderator privledges.
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
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
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}¬es=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}¬es=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}¬es=note text. . .&reasonId=#&versionNumber={version}
Note:
The user must be logged in.
The user must have moderator privledges.
22
NARA Catalog Authorized User API
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}¬es=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
NARA Catalog Authorized User API
"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
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
3.8.1.1 Error Codes
The following error codes are currently defined as part of the API response:
Error Code Description Parameters
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
NARA Catalog Authorized User API
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
NARA Catalog Authorized User API
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:
Error Code Description Parameters
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
NARA Catalog Authorized User API
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