readme.md

internet-archive-metadata-api

internet archive metadata api helper methods.

the methods in this module have been created based on the The Internet Archive Metadata API blog post, which apply to internet archive items that already exist in the internet archive database.

table of contents

• installation
• use
  • getRequestOptions( user_options, request_headers )
    • user_options ( get )
      • count
      • identifier
      • index
      • start
      • type
    • request-headers ( get/post )
    • api-endpoints
    • basic
  • read( user_options, request_headers )
    • user_options ( read )
    • request-headers ( read )
    • basic
  • postRequestOptions( user_options, request_headers )
    • user_options ( post )
      • access
      • identifier
      • patch
      • secret
      • target
    • request-headers ( write )
    • basic
  • write( user_options, request_headers )
    • user_options
    • request-headers
    • basic
• license

installation

npm install internet-archive-metadata-api

use

this module provides two main methods: read and write, however, getRequestOptions and postRequestOptions are also exposed for those that would rather initiate the request in a different manner than this module does with request-as-bluebird.

getRequestOptions( [user_options][, request_headers] )

 * @param {Object} [user_options]
 * @param {Object} [request_options]
 * @returns {Object}

user_options ( get )

var user_options = {
  count: number,
  identifier: string,
  index: number,
  start: number
  type: string
};

count ( optional )

used in conjunction with the files endpoint to indicate the limit of file objects returned.

identifier ( required )

used in conjunction with all endpoints to determine which resource to retrieve.

index ( optional )

used in the collection_index and files_index endpoints.

start ( optional )

used in conjunction with the files endpoint to indicate which file object, in the total file list available, to begin returning.

type ( optional )

used in conjunction with all endpoints, defaults to all.

request_headers ( get/post )

this object refers the request_headers object used by the generic-request-options module, which is used internally by this module.

api-endpoints

api-endpoints available can be found in the get-api-endpoint.js file and refer to the Sub-item Access section of the internet archive metadata api documentation.

the colon prefixed terms in the api endpoint urls are replaced with matching user_options properties; e.g. :identifier, and :index would be replaced with values indicated in the user_options object.

basic ( getRequestOptions )

var getRequestOptions = require( 'internet-archive-metadata-api' ).getRequestOptions;

var user_options = {
  identifier: 'frenchenglishmed00gorduoft',
  index: 1,
  type: 'collection_index'
};

var request_options = getRequestOptions( user_options );

request_options => {
  identifier: 'frenchenglishmed00gorduoft',
  index: 1,
  type: 'collection_index',
  headers: { 'user-agent': 'node.js/v4.6.0 request (https://www.npmjs.com/package/request)' },
  timeout: 10000,
  method: 'get',
  qs: {},
  url: 'https://archive.org/metadata/frenchenglishmed00gorduoft/metadata/collection/1' 
}

read( [user_options][, request_headers] )

 * @param {Object} [user_options]
 * @param {Object} [request_options]
 * @returns {Promise.<{ body:string, response:IncomingMessage }>}

user_options ( read )

see user_options ( get )

request_headers ( read )

see request_headers ( get/post )

basic ( read )

var read = require( 'internet-archive-metadata-api' ).read;
var user_options = { identifier: 'frenchenglishmed00gorduoft' };

read( user_options )
  .then(
    /**
     *  {{ body:string, response:IncomingMessage }} result
     */
    function( result ) {
      var json = JSON.parse( result.body );
    }
  )
  .catch();

postRequestOptions( [user_options][, request_headers] )

 * @param {Object} [user_options]
 * @param {Object} [request_options]
 * @returns {Object}

user_options ( post )

var user_options = {
  access: string,
  identifier: string,
  patch: string,
  secret: string,
  target: string
};

access ( required )

your ia-s3 access key, which can be obtained by logging into your internet archive account and requesting an ia-s3 key.

identifier ( required )

determines which internet archive resource will be affected by the write.

patch ( required )

the updates you want to apply to the internet archive item indicated by the identifier. they should be a string containing an array of valid json patches 02. for example:

patch: '[ { "add": "/description", "value": "Testing the limits ..." }, { "add": "/publisher", "value": "Philadelphia P. Blakiston" } ]'

secret ( required )

your ia-s3 secret key, which can be obtained by logging into your internet archive account and requesting an ia-s3 key.

target ( required )

one of the following values:

• metadata
  • targets the metadata object for the item, which can be viewed at http://archive.org/metadata/:identifier/metadata; e.g., http://archive.org/metadata/frenchenglishmed00gorduoft/metadata
• files/:filename
  • targets the file metadata for the item indicated by the identifier
  • replace :filename with the filename you wish to affect
    • a list of available files; e.g., http://archive.org/metadata/frenchenglishmed00gorduoft/files
    • target the frenchenglishmed00gorduoft_marc.xml file by setting the target to files/frenchenglishmed00gorduoft_marc.xml
• other
  • targets the other object for the item, which can be viewed at http://archive.org/metadata/:identifier/other; e.g., http://archive.org/metadata/frenchenglishmed00gorduoft/other

basic ( postRequestOptions )

var postRequestOptions = require( 'internet-archive-metadata-api' ).postRequestOptions;

var user_options = {
  access: 's3-access-token',
  identifier: 'test-api',
  patch: '[ { "add": "/description", "value": "Testing the limits ..." }, { "add": "/publisher", "value": "Philadelphia P. Blakiston" } ]',
  secret: 's3-secret',
  target: 'metadata'
};

var request_options = postRequestOptions( user_options );

request_options => {
  headers: { 'user-agent': 'node.js/v4.6.0 request (https://www.npmjs.com/package/request)' },
  form: {
    access: 's3-access-token',
    '-patch': '%5B%20%7B%20%22add%22%3A%20%22%2Fdescription%22%2C%20%22value%22%3A%20%22Testing%20the%20limits%20...%22%20%7D%2C%20%7B%20%22add%22%3A%20%22%2Fpublisher%22%2C%20%22value%22%3A%20%22Philadelphia%20P.%20Blakiston%22%20%7D%20%5D',
    secret: 's3-secret',
    '-target': 'metadata'
  },
  method: 'post',
  timeout: 10000,
  url: 'https://archive.org/metadata/test-api'
}

write( [user_options][, request_headers] )

 * @param {Object} [user_options]
 * @param {Object} [request_options]
 * @returns {Promise.<{ body:string, response:IncomingMessage }>}

user_options ( write )

see user_options ( post )

request_headers ( write )

see request_headers ( get/post )

basic ( write )

var write = require( 'internet-archive-metadata-api' ).write;

var user_options = {
  access: '<your-ia-s3-access-token>',
  identifier: 'test-api',
  patch: '[ { "add": "/publisher", "value": "Philadelphia P. Blakiston" } ]',
  secret: '<your-ia-s3-secret>',
  target: 'metadata'
};

write( user_options )
  .then(
    /**
     *  {{ body:string, response:IncomingMessage }} result
     */
    function( result ) {
      var json = JSON.parse( result.body );
    }
  )
  .catch();

license

MIT License