Skip to content

dan-nl/internet-archive-metadata-api

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

24 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

internet-archive-metadata-api

NPM version Build Status Coverage Status Dependency Status Dev Dependency Status NSP Status

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

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:

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

About

internet archive metadata api helper methods

Resources

License

Stars

Watchers

Forks

Packages

No packages published