grunt-github-api

grunt-github-api

Query Github's API and save the returned JSON files locally.

Project authored and maintained by github/https://github.com/jeffHerb.

Getting Started

This plugin requires Grunt ~0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-github-api --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-github-api');

Run this task with the grunt github command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide.

Options

Options for this plugin are broken down into sub-option categories as defined below. Please note that all option sections by default are objects and contain simple key-value pairs unless otherwise noted.

output

Used to idenify where cache and downloaded request data should be stored by default

• path: default: 'api-data' - special location where all data is collected when saved to disk, when no specific destination is definded under the targets dest.
• cache: default: '.cache.json' - plugin cache file name. Will be stored under under the output path defined above.

format

• indent: default: 4 - number of spaces each indent should take up.
• encoding: default: 'utf8' - file format all data written to disk should be in.

Examples:

{
  options: {
    output: {
      path: 'my/api/data/',
      cache: 'my/api/cache/'
      format: {
        indent: 4,
        encoding: 'utf8'
      }
    }
  }
}

connection

Connection headers used when connecting the GitHub.

• host: default: api.github.com - default GitHub API portal
• headers: default: {Object} used to define the nodejs HTTPS headers.
  • User-Agent: node-http/0.10.1
  • Content-Type: application/json

Examples:

{
  options: {
    connection: {
      host: 'api.github.com',
      headers: {
        'User-Agent': 'node-http/0.10.1',
        'Content-Type': 'application/json'
      }
    }
  }
}

type

Type of data the task will be downloading

Indicates the type of request, may be set to either data or file. Default is data.

cache

Control which files do or do not get tracked for changes.

Specifies whether or not to cache API responses. Default is true.

concat

Concatinate JSON data together before writting it to a file when property is set to true. Default is false.

filters

Query search parameters

Additional information about different filters can be found in the Github Developer Documentation.

oAuth

GitHub access credentials

These credentials are required to preform many actions or continual usage of the plugin. In order to get access using oAuth the repo owner will need to create an access token via their Application Settings page.

Usage Examples

Targets

• src: is the specified API query path. Source paths are everything that appears after api.github.com. Additional information about different query paths can be found in the Github Developer Documentation. The src can be an array or a string value.
• dest: (optional) - is the path and filename where the retured request should be saved. If nothing is given files will be saved into the same path as the task cache file and will be broken down into a folder structure that mimics its query path. (EXCEPTION: If you define multiple sources that are being concatenated together, you must define at least a filename).

Configuration

Options may be defined at either the task and/or target levels (target-level options override task-level options).

github: {
  // Concatentate returned JSON responses into a single file.
  combindedIssues: {
    options: {
      filters: {
        state: 'open'
      },
      task: {
        concat: true
      }
    },
    src: [
      '/repos/assemble/grunt-github-api-example/issues',
      '/repos/assemble/grunt-github-api/issues'
    ],
    dest: 'combinded-issues.json'
    // File created will be save along the gruntfile.
  },

  // Create two different files from two different repos.
  seperateIssues: {
    options: {
      // Access repo using credentials provided
      oAuth: {
        access_token: 'XXXXXXXXXXXXXXXXXX'
      }
    },
    src: [
      '/repos/assemble/grunt-github-api-example/issues',
      '/repos/assemble/grunt-github-api/issues'
    ]
    // Files created will be saved inside the api-data folder
  },

  // Downloads a copy of the example.json file from GitHub.
  examplePkg: {
    options: {
      task: {
        type: 'file',
      }
    },
    src: '/repos/assemble/grunt-github-api-example/contents/example.json'
    // File created will be saved inside the api-data folder
  }
}

Contributing

Please see the Contributing to Assemble guide for information on contributing to this project.

Author

• github/https://github.com/jeffHerb

License

Copyright (c) 2013 Jeffrey Herb, contributors. Released under the MIT license

This file was generated on Tue Oct 29 2013 21:13:51.