Search Technologies Assessment - Archives



National Archives and Records AdministrationNational Archives Catalog (The Catalog)Authorized User API– Catalog Perspective –Status-FinalVersion 1.7September 3, 2015National Archives & Records AdministrationNARA Catalog Authorized User APIVersion 1.7Contract Number GS-35F-0541UOrder Number NAMA-13-F-0120September 3, 2015Contents TOC \o "2-3" \h \z \t "Heading 1,1" 1Overview PAGEREF _Toc424217943 \h 21.1Other Relevant Documents PAGEREF _Toc424217944 \h 21.2Relation to API Reference Guide PAGEREF _Toc424217945 \h 22Account Administrator API PAGEREF _Toc424217946 \h 32.1Creating Accounts PAGEREF _Toc424217947 \h 32.2Searching for Accounts PAGEREF _Toc424217948 \h 42.3Fetching User Notes PAGEREF _Toc424217949 \h 72.4Editing User Information PAGEREF _Toc424217950 \h 83Moderating Contributions PAGEREF _Toc424217951 \h 123.1Viewing the Contributions Stream PAGEREF _Toc424217952 \h 123.1.1Parameters PAGEREF _Toc424217953 \h 123.1.2Response PAGEREF _Toc424217954 \h 123.1.3Examples PAGEREF _Toc424217955 \h 143.1.4Error Codes PAGEREF _Toc424217956 \h 173.2Fetching an Individual Contribution PAGEREF _Toc424217957 \h 183.3Fetching Contribution Notes PAGEREF _Toc424217958 \h 193.4Fetching List of Transcription / Translation Versions PAGEREF _Toc424217959 \h 203.5Fetching a Specific Version PAGEREF _Toc424217960 \h 213.5.1Parameters PAGEREF _Toc424217961 \h 233.5.2Response PAGEREF _Toc424217962 \h 233.6Contribution Removal PAGEREF _Toc424217976 \h 233.6.1Authorization credentials PAGEREF _Toc424217977 \h 233.6.2Removing Contributions PAGEREF _Toc424217978 \h 243.7Background images PAGEREF _Toc424217979 \h 253.7.1Adding a background image PAGEREF _Toc424217980 \h 253.7.2Fetching background images PAGEREF _Toc424217981 \h 273.7.3Deleting background images PAGEREF _Toc424217982 \h 273.7.4Fetching background images for User Interface PAGEREF _Toc424217983 \h 273.8Online Availability header PAGEREF _Toc424217984 \h 283.8.1Updating the online availability header PAGEREF _Toc424217985 \h 283.8.2Fetching online availability header PAGEREF _Toc424217986 \h 293.8.3Restoring online availability header PAGEREF _Toc424217987 \h 303.8.4Removing online availability header PAGEREF _Toc424217988 \h 30Version ControlVersionDateReviewerSummary Description0.12014-03-04Paul NelsonInitial Version. Complete account administration section.0.22014-03-08Paul NelsonFirst complete version0.32014-03-09Kristy MartinInternal review1.02104-03-10Initial Release1.12014-11-14Brandon StahlRemoved “Confidential to Search Technologies” text from footer1.22014-11-24Brandon StahlReplaced url with url1.32015-03-17Luis VargasAdded miscellaneous items for Congressional Fields1.42015-03-26Luis VargasRemoved miscellaneous items for Congressional Fields1.52015-07-09Luis Vargas, Alejandro Baltodano, Kristy MartinAdded annotation removal API methodsChanged branding for system name throughout document. Added cover sheetAdded sections 3.7 and 3.81.62015-08-06Brandon StahlAdded Invalid_Login error code1.72015-09-03Alejandro BaltodanoUpdated examplesOverviewThis document provides the details of the APIs for handling authorized user requests.Specifically, this document will cover:Account Administration APIModerators APIOther Relevant DocumentsOther documents relevant to this document:NARA Catalog User Interface DesignIdentifies all end-user functionality which must be supported by these APIs. NARA Catalog Architecture DesignExplains the data model for information in the Catalog.NARA Catalog API Reference GuideProvides all of the APIs for public user.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.Account Administrator APIThis 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 accountsSearching for accountsSpecifying a reason and note when deactivating accountsViewing reasons and notesResetting passwordsCreating AccountsUse the following URL for creating accounts:POST (SSL) protocol is absolutely required whenever modifying account information.Standard HTTP requests will be rejected.Log in is required.Only users with “accountAdmin” rights can create accounts.Note that the POST HTTP Method is required.ParametersParameterDescriptionExamplesuserType=standard|powerSpecify the user type. If not specified, “standard” is assumed.userType=poweruserType=standardFor use when action=changerights=moderator,accountAdmin,accountAdminModSpecify additional rights for the user. This can be either moderator, accountAdmin, or accountAdminMod.rights=moderatorrights=accountAdminemail=emailSpecify the new e-mail address for the user.email=jdoe@fullName=full-nameSpecify the new full name for the user.fullName=Thomas%20JeffersondisplayFullName=true|falseSet to “true” if the full name for the user should be displayed to the public, “false” otherwise.displayFullName=trueExamplesCreate a new account:POST &email=bclinton@&fullName=William Jefferson Clinton&displayFullName=true&password=P@sswordResponseThe response will the standard Catalog response (see the NARA Catalog API Reference Guide for more information).Error CodesIf the paging parameters are incorrect, then a standard error header will be returned with one of the following error codes:Error CodeDescriptionParametersNOT_LOGGED_INAttempt to view or modify account information without logging in.noneINSUFFICIENT_RIGHTSAttempted to add an account without account admin rights.request: The user ID who made the request.USERNAME_EXISTSAttempted to create an account with a username which already exists.request: The user ID which already exists.EMAIL_EXISTSSpecified email address already registered to another user.email: Requested E-mail.currentUser: The user to which the e-mail is already registered.INVALID_LOGINAttempt to log in with incorrect credentials.User; User ID entered.Password: Password entered.Searching for AccountsUse the following URL for search for accounts:GET (SSL) protocol is absolutely required whenever searching account information.Standard HTTP requests will be rejected.Log in is required.Only users with “accountAdmin” rights can search accounts.ParametersParameterDescriptionExamplesaction=searchUsed to distinguish search requests from other sorts of requests (for future use).action=searchFor use when action=changefieldName=search-stringSpecify 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=martinid=mar&email=comcastfullName=george&status=inactivesort=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 ascsort=userType descoffset=#Specify the starting row number for the results to show. With rows, this can be used to page the results.offset=0offset=100rows=#Specify the number of rows to return in the results.rows=25rows=100ExamplesCreate a new account:GET desc&offset=0&rows=25ResponseThe 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 desc&offset=0&rows=25{ "users":{ “@total”:”2”, “@searchTotal”:”2”, “user”:[ { "internalId":12345, "id":"tjefferson", "type":"standard", "rights”:”regular”, "fullName":"Thomas Jefferson", "email":"tjefferson@", "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":"gjefferson@", "status":"active", "hasNote":false, "isNaraStaff”:true, "accountCreatedTs”:”2014-05-06T18:45:12:000Z” } ]}XML ExampleGET 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>tjefferson@</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>gjefferson@</email> <status>active</status> <hasNotes>false</hasNotes> <isNaraStaff>true</isNaraStaff> <accountCreatedTs>2014-05-06T18:45:12:000Z</accountCreatedTs> </user></users>Error CodesIf the paging parameters are incorrect, then a standard error header will be returned with one of the following error codes:Error CodeDescriptionParametersNOT_LOGGED_INAttempt to view or modify account information without logging in.noneINSUFFICIENT_RIGHTSAttempted to add an account without account admin rights.request: The user ID who made the request.INVALID_PARAM_VALUEThe 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_LOGINAttempt to log in with incorrect credentials.User; User ID entered.Password: Password entered.Fetching User NotesUser notes can be fetched with the following URL:GET (SSL) protocol is absolutely required whenever searching account information.Standard HTTP requests will be rejected.Log in is required.Only users with “accountAdmin” rights can fetch user notes.ResponseThe 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"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 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"> User appears to be spamming the system </note></user>Editing User InformationAccount information can be viewed and modified using the following URL:PUT (SSL) protocol is absolutely required whenever modifying account information.Standard HTTP requests will be rejected.The user must be logged in.The user must have account administrator privledges.ParametersParameterDescriptionExamplesaction=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=adminChangeuserType=standard|powerSpecify the new user type. Generally, power users have fewer limits on resource usage than standard users.type=standardtype=powerrights=regular|moderator|accountAdmin|accountAdminModSpecify 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=accountAdminrights=moderatoremail=emailSpecify the new e-mail address for the user.email=jdoe@fullName=full-nameSpecify the new full name for the user.fullName=Thomas%20JeffersondisplayFullName=true|falseSet to “true” if the full name for the user should be displayed to the public, “false” otherwise.displayFullName=truestatus=active|inactiveSpecify the new status for the user.status=activestatus=inactivereasonId=#Specify the ID number of the reason to be saved with the edit.See section REF _Ref381737655 \r \h 0 for more information on fetching lists of reasons. Only required if the action is to deactivate the user.reason=32notes=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.ExamplesChange the tjefferson’s E-mail:PUT tjefferson:PUT is obviously face. Everyone knows that Thomas Jefferson prefers using a quill instead of a computer.Reset tjefferson’s password:PUT 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{ "header":{ "@status":"200", "@time":"2014-05-31T16:15:47.715Z", "request":{ "@path":"/api/v1/users/tjefferson/account", "action":"resetPassword" } }, "user":”success”}XML ExamplePUT 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 CodesIf the paging parameters are incorrect, then a standard error header will be returned with one of the following error codes:Error CodeDescriptionParametersNOT_LOGGED_INAttempt to view or modify account information without logging in.noneNOT_OWNERAttempt to modify the account information for other users.request: The user ID who made the request.MISSING_NOTENotes are required when an account is deactivated.noneMISSING_REASONA reason code is required when an account is deactivated.noneINVALID_LOGINAttempt to log in with incorrect credentials.User; User ID entered.Password: Password entered.Moderating ContributionsThis section covers the methods available for moderators to moderate the stream of contributions.Viewing the Contributions StreamAll user contributions are viewable as a stream of updates, using the following URL:GET user must be logged in.The user must have moderator privledges.ParametersAll of the user contribution methods support several common parameters for paging and sorting.ParameterDescriptionExamplesoffset=#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=50filterType=TG|CM|TR|ModeratorSpecify what items to show in the stream.filterType=TGfilterType=ModeratornaId=<naid>Specify an NAID to filter the results.naId=7229324ResponseThe 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.contribution – parent tag which holds all information about each contribution.@transId – The transaction ID for the contribution.@type – The type of contribution.One of “comment”, “reply”, “tag”, “transacription” or “translation”.@on – Identifies what in the Catalog system was annotated.One of “person”, “organization”, “description”, or “object”.@when – Specifies the date and time when the contribution occurred.@userId – Specifies the account ID (username) of the user who was responsible for the contribution.@fullName – The full name of the user.@isNaraStaff – “true” if the user is a NARA staff member.@authorUserId – Specifies the account ID (username) of the user who created the contribution.@authorFullName – The full name of the user who created the contribution.@authorDisplayFullName – “true” if the author’s fullname should be displayed.@authorIsNaraStaff – “true” if the author is a NARA staff member.@action – The action associated with this contribution.Can be one of “new”, “update”, “remove”, or “restore”.@hasNote – “true” if there are moderator notes associated with the contribution.@notes – Notes added after an action was performed.@reason – Reason specified after an action was performed.title – A display title for the contribution. Usually the title of the associated description or authority record.accessPath – The API path for accessing the item to which the contribution was ment – Parent tag, included if @type=”comment”.@id – The ID for this comment.text – The text of the comment.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.tag – Parent tag, included if @type=”tag”.text – The text of the tag.transcription – Parent tag, included if @type=”transcription”.teaser – Holds “teaser text” for the transcription, the first 200 characters or so of the transcription.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.description – Parent tag, included if @on=”description”.@naid – The NAID of the description on which the comment was made.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.person – Parent tag, included if @on=”person”.@id – The person ID anization – Parent tag, included if @on=”organization”.@id – The organization ID number.ExamplesJSON ExampleGET{ "@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", "@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", "@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 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> <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>Error CodesIf the paging parameters are incorrect, then a standard error header will be returned (see section REF _Ref379726032 \r \h Error! Reference source not found.) with one of the following error codes:Error CodeDescriptionParametersINVALID_OFFSETAn incorrect offset was requested.offset: The requested offset.avail: The number of rows available.INVALID_ROWSA “rows” number less than zero was requested.rows: The requested rows.TOO_MANY_ROWSToo many rows were requested.rows: The requested rows.max: The maximum number of rows allowed.INVALID_SORTInvalid sort field or sort direction requested.noneFetching an Individual ContributionAll user contributions are viewable as a stream of updates, using the following URL:GET user must be logged in.The user must have moderator privledges.The data returned will be the same as described in section REF _Ref381975386 \r \h 3.1.2. If the ID does not exist, a 404 error will be returned.JSON ExampleGET{ "@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 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> <object naid="7283080" id="263" display="2/11"/></contribution>Fetching Contribution NotesAll contributions from the contributions stream, can be deleted or restored using the following URL:GET user must be logged in.The user must have moderator privledges.ResponseThe 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:@adminId – Holds the moderator ID which made the change.@action – Holds the action made by the moderator.One of “remove” or “restore”.@when – Holds the date the note was created.@reason – Holds the textual version of the reason code.@reasonId – Holds the ID version of the reason code.JSON ExampleGET{ "@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 " }, { "@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 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>Fetching List of Transcription / Translation VersionsTranscriptions – list of versions:GET{naid}/objects/{obj-id}Translations – list of versions:GET{naid}/objects/{obj-id}?language=<language>Note:The user must be logged in.The user must have moderator privledges.ResponseVersions 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.Either “transcription” or “translation”.@code – The languge code of the translation.version – Parent tag which contains information about a specific version. Contains the following sub-elements:@num – The version number. An incrementing number from 1 (first version) to N (last version).@action – What happened to cause the version. One of “save”, “remove” or “restore”.@when – The date-time when the version was created.JSON ExampleGET{ "@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 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>Fetching a Specific VersionUse the following URLs to fetch a specific version of a transcription or translation.Transcriptions – specific version:GET{naid}/objects/{obj-id}?version={version-number}Translations – specific version:GET{naid}/objects/{obj-id}?language={language}&version={version-number}ResponseThe 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.Deleting and Restoring Contributions.All contributions from the contributions stream, can be deleted or restored using the following URL:Deleting and restoring comments:DELETE{naid}/{comment-id}?notes=note text. . .&reasonId=#PUT{naid}/{comment-id}?notes=note text. . .&reasonId=#Deleting and restoring replies:DELETE{naid}/{comment-id}?notes=note text. . .&reasonId=#PUT{naid}/{comment-id}?notes=note text.. .&reasonId=#Deleting and restoring transcriptions:DELETE{naid}/objects/{obj-id}?notes=note text. . .&reasonId=#&versionNumber={version}PUT{naid}/objects/{obj-id}?versionNumber={version-number}&notes=note text. . .&reasonId=#&versionNumber={version}Deleting and restoring translations:DELETE{naid}/objects/{obj-id}?language={lang-code}&notes=note text. . .&reasonId=#&versionNumber={version}PUT{naid}/objects/{obj-id}?language={lang-code}&versionNumber={version-number}&notes=note text. . .&reasonId=#&versionNumber={version}Note:The user must be logged in.The user must have moderator privledges.ParametersAll of the user contribution methods support several common parameters for paging and sorting.ParameterDescriptionExamplesaction=moderatorRestore|moderatorRemoveSpecify that this is a moderator restore or remove action, instead of an end-user modify action.action=restorenotes=note text. . .Specify a textual note to save with the action.notes=Obviously spamreasonId=#The reason number for the change.reason=6ExamplesDELETE to be spam&reasonId=4PUT unusual middle name for spam&reasonId=6DELETE foul language&reasonId=4PUT{version-number}&notes=Mistaken removal&reasonId=7ResponseA standard Catalog response will be returned (either success or failure).Contribution RemovalAPI provides methods to remove contributions by a moderator user.Authorization credentialsJust like with adding annotations, using the moderator API requires the Authorization http header with the credentials code that is received in the login response: "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>”Removing ContributionsContributions are removed by the moderator using the DELETE Http mentsAs a moderator, use the following requests to remove a comment:DELETE{naId}/{annotationId}?reasonId=<reason id>DELETE {naId}/objects/{objectId}/{annotationId}?reasonId=<reason id>TagsAs a moderator, use the following requests to remove a tag:DELETE{naId}?text={tag text}&reasonId={reason id}DELETE {naId}/objects/{objectId}/{annotationId}?reasonId={reason id}&text={tag text}TranscriptionsAs a moderator, use the following request to remove a transcription:DELETE {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.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 the list of configured images in Catalog:GET can fetch a specific image providing the naId and objectId of the image:GET a background image from Catalog:DELETE a background imageUse the following URL to add a background image:GET 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.ResponseIn 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 naId="1667921" objectId="14721075" title="Photograph of Richard M. Nixon Shaking Hands with Entertainer Elvis Presley in the Oval Office" path=""></background-image>JSON ExampleGET"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.\/shrink-images\/1667921-5598_2004_a.jpg" }Error CodesThe following error codes are currently defined as part of the API response:Error CodeDescriptionParametersBACKGROUND_IMAGE_NOT_FOUNDAn invalid or non-existing object was used in the request.noneA 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/13087218Default background images should be separated by semi-colon character, and the format should be naId/objectId.Fetching background imagesA list of configured images in Catalog can be retrieved using the following URL:GET can fetch a specific image providing the naId and objectId of the image:GET example:GET background imagesBackground images can be deleted from Catalog using the following URL:DELETE example:DELETE background images for User InterfaceBackground images can be retrieved by the User Interface using the following URL:GET example:GET 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 the online availability header for a description:POST the online availability header for a description:PUT the online availability header for a description:DELETE the online availability headerUse the following URL to update the online availability header for a description:POST 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. 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 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.&nbsp;</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"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.&nbsp;<\/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" } ] }Error CodesThe following error codes are currently defined as part of the API response:Error CodeDescriptionParametersINVALID_ID_VALUEAn invalid or non-existing naId was entered.noneONLINE_AVALIABILITY_HEADER_NOT_FOUNDOnline availability header not found for the description.noneFetching online availability headerThe online availability header for a description can be retrieved using the following URL:GET example:GET online availability headerThe online availability header for a description can be restored using the following URL:PUT example:PUT online availability headerThe online availability header for a description can be removed using the following URL:DELETE example:DELETE ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download