Checkvist story

OpenAPI usage examples (Javascript, Ruby)

We’ve got a number of requests to provide some examples of accessing Checkvist via OpenAPI. When I started preparing one, I found some inconsistencies in the OpenAPI docs and in the implementation. These issues have been fixed and now I’d like to give you some code examples.

In the examples, I’ll demonstrate usage of the JSON format for the returning data. Checkvist API also supports XML format, for details, please see the documentation.

Javascript

The Javascript example illustrates how to obtain checklist tasks data and embed the list into your web page.

The list will be organized into a hierarchy with simple UL tags. Completed tasks in the list will be striked, invalidated tasks are marked with italics. The parent UL tag will have CSS class checkvist_list to enable styling according to your needs.

Here is a sample of the generated HTML code:

<ul class="checkvist_list">
  <li>This is an item</li>
  <li>This is another item
      <ul>
        <li>This is a subitem</li>
        <li><strike>This is a completed subitem</strike></li>
        <li><em>This is invalidated subitem</em></li>
      </ul>
  </li>
</ul>

To embed the checklist, follow these steps:

Step 1. Add Javascript library for accessing Checkvist

In the HEAD section of your web page, add the following line:

<script type="text/javascript" 
src="http://checkvist.com/javascript/checkvist_api.js"></script>

This sample library contains the code which accesses the Checkvist via OpenAPI and builds HTML for embedding into web page. You can download it and customize for your needs, if you want.

Step 2. Prepare target location for the embedded checklist

Add the following markup on your page at the place where you want to see the checklist:

<div id="checklist_container"></div>

Step 3. Determine the ID of the checklist you want to embed

This is an easy part. If your checklist has URL like http://checkvist.com/checklists/3318-checkvist-test-plan, than required checklist ID is 3318.

Step 4. Get your OpenAPI key

Visit your CheckVist profile page and click “View/update remote OpenAPI key” link. Copy the key from the text field.

Step 5. Add code which actually loads the checklist

Add the following block in the HEAD section of your Web page:

<script type="text/javascript">
  function load_checklist_callback(data) {
    document.getElementById('checklist_container').innerHTML =
         checkvist.create_tasks_html(data);
  }
  function load_checklist() {
    // Remove the next line if your checklist is public
    checkvist.login('Your E-Mail', 'Your OpenID KEY');
    checkvist.get_tasks(<Checklist ID>, 'load_checklist_callback');
  }
  
  var checkvist_interval = setInterval(function() {
    if (document.getElementById('checklist_container')) {
      clearInterval(checkvist_interval);
      load_checklist();
    }
  }, 20);
</script>

In this code, you need to specify your login to CheckVist - e-mail address, OpenAPI key, and checklist ID to show.

If your checklist is public, there is no need to authenticate, so checkvist.login call can be omitted.

Actually, instead of calling setInterval function, you can invoke method load_checklist in your usual place of Javascript initialization code for your web page.

That’s it. When the page is loaded, the element checklist_container will be filled with checklist tasks. You can take a look at the checkvist_api.js and use it as a base for solving more complex tasks.

Ruby

As long as Checkvist OpenAPI is HTTP-based, you can use a standard Net::HTTP module to create requests, and JSON gem to parse responses.

Here is a sample class for accessing Checkvist from Ruby:

require 'net/http'
require 'uri'
require 'rubygems'
require 'json'

class SampleCheckvistApi 

  def initialize email = nil, api_key = nil, site = "http://checkvist.com"
    @email = email
    @api_key = api_key
    @url = URI.parse(site)
  end

  # Obtain a list of checklists
  def checklists()
    json_call Net::HTTP::Get.new("/checklists.json")
  end

  # Obtain a list of tasks for given checklist
  def tasks(checklist_id)
    json_call Net::HTTP::Get.new("/checklists/#{checklist_id}/tasks.json")
  end

  # create a task in given checklist
  def create_task(checklist_id, content, parent_task_id = nil, position = nil)
    json_call Net::HTTP::Post.new("/checklists/#{checklist_id}/tasks.json"), 
      { "task[parent_id]" => parent_task_id, 
        "task[position]" => position, 
        "task[content]" => content }
  end
  
  # update a task attribute. For task attributes, you can use "content", "parent_id", "position"
  def update_task_attribute(checklist_id, task_id, attr_name, attr_value)
    json_call Net::HTTP::Put.new("/checklists/#{checklist_id}/tasks/#{task_id}.json"), {"task[#{attr_name}]" => attr_value}
  end
  
  def json_call request, parameters = nil
    request.basic_auth @email, @api_key if @email
    request.set_form_data(parameters) if parameters
    
    res = Net::HTTP.start(@url.host, @url.port) { |http|
      http.request(request)
    }
    
    case res
    when Net::HTTPSuccess
      JSON.parse(res.body)
    else
      res.error!
    end
  end

end

And here is a sample of how to use SampleCheckvistApi class:

  # Specify authentication data:
  api = SampleCheckvistApi.new('email', 'OpenAPI key')

  # For each public non-archived checklist
  api.checklists.each do |checklist|
    # Obtain its tasks:
    tasks = api.tasks(checklist['id'])
    # Tasks are sorted by parent_id, position 
  end


  # Create a task in the first checklist
  # Get ID of the first checklist:
  first_checklist_id = api.checklists[0]["id"]

  # Create the task at the end of the checklist:
  new_task = api.create_task(checklist_id, "new task from api")

  # Change task content to 'new text'
  api.update_task_attribute(new_task['checklist_id'], 
      new_task['id'], "content", "new text")
  # Change the parent of the task:
  api.update_task_attribute(new_task['checklist_id'], 
      new_task['id'], "parent_id", tasks[0]['id'])

If you’re interested in using Checkvist API, or you’re going to use it, please let us know :). You may also want to subscribe to the checkvist-api newsgroup.

Good luck!
KIR