From ac5590f9231f7409d95d8ff32b17bb48595b4908 Mon Sep 17 00:00:00 2001 From: lukemelia Date: Wed, 5 Dec 2007 06:48:24 +0000 Subject: [PATCH] Added documentation for REST API. git-svn-id: http://www.rousette.org.uk/svn/tracks-repos/trunk@674 a4c988fc-2ded-0310-b66e-134b36920a42 --- .../controllers/integrations_controller.rb | 4 + tracks/app/controllers/todos_controller.rb | 6 + tracks/app/views/integrations/index.rhtml | 14 +- tracks/app/views/integrations/rest_api.rhtml | 218 ++++++++++++++++++ tracks/doc/tracks_api_wrapper.rb | 19 ++ 5 files changed, 254 insertions(+), 7 deletions(-) create mode 100644 tracks/app/views/integrations/rest_api.rhtml diff --git a/tracks/app/controllers/integrations_controller.rb b/tracks/app/controllers/integrations_controller.rb index 542c8bb4..1b071c1e 100644 --- a/tracks/app/controllers/integrations_controller.rb +++ b/tracks/app/controllers/integrations_controller.rb @@ -4,6 +4,10 @@ class IntegrationsController < ApplicationController @page_title = 'TRACKS::Integrations' end + def rest_api + @page_title = 'TRACKS::REST API Documentation' + end + def get_quicksilver_applescript context = current_user.contexts.find params[:context_id] render :partial => 'quicksilver_applescript', :locals => { :context => context } diff --git a/tracks/app/controllers/todos_controller.rb b/tracks/app/controllers/todos_controller.rb index 53be78ca..c89c8616 100644 --- a/tracks/app/controllers/todos_controller.rb +++ b/tracks/app/controllers/todos_controller.rb @@ -116,6 +116,7 @@ class TodosController < ApplicationController end render end + format.xml { render :xml => @todo.to_xml( :except => :user_id ) } format.html do if @saved # TODO: I think this will work, but can't figure out how to test it @@ -132,6 +133,10 @@ class TodosController < ApplicationController def toggle_star @todo.toggle_star! @saved = @todo.save! + respond_to do |format| + format.js + format.xml { render :xml => @todo.to_xml( :except => :user_id ) } + end end def update @@ -189,6 +194,7 @@ class TodosController < ApplicationController determine_down_count respond_to do |format| format.js + format.xml { render :xml => @todo.to_xml( :except => :user_id ) } format.m do if @saved redirect_to formatted_todos_path(:m) diff --git a/tracks/app/views/integrations/index.rhtml b/tracks/app/views/integrations/index.rhtml index 6ee51b92..18440b3f 100644 --- a/tracks/app/views/integrations/index.rhtml +++ b/tracks/app/views/integrations/index.rhtml @@ -1,11 +1,11 @@

Integrations

-

Tracks can be integrated with a number of other tools... whatever it takes to help you get things done! This page has information on setting up some of these. Not all of these are applicable to all platforms, and some require more technical knowledge than others.

+

Tracks can be integrated with a number of other tools... whatever it takes to help you get things done! This page has information on setting up some of these. Not all of these are applicable to all platforms, and some require more technical knowledge than others. See also <%= link_to "developer documentation for Tracks' REST API", url_for(:action => 'rest_api') %>.

Contents: -

    -
  1. Add an Action with Applescript
    2. -
  2. Add an Action with Applescript based on the currently selected Email in Mail.app
    3. -
  3. Add Actions with Quicksilver and Applescript
    4. -
  4. Automatically Email Yourself Upcoming Actions
    5. +
      +
    1. Add an Action with Applescript
      2. +
    2. Add an Action with Applescript based on the currently selected Email in Mail.app
      3. +
    3. Add Actions with Quicksilver and Applescript
      4. +
    4. Automatically Email Yourself Upcoming Actions

    Do you have one of your own to add? Tell us about it in our Tips and Tricks forum @@ -16,7 +16,7 @@

    This is a simple script that pops up a dialog box asking for a description, and then sends that to Tracks with a hard-coded context.

      -
    1. Choose the context you want to add actions to: +
    2. Choose the context you want to add actions to: <%= observe_field "applescript1-contexts", :update => "applescript1", :with => 'context_id', :url => { :controller => "integrations", :action => "get_applescript1" }, diff --git a/tracks/app/views/integrations/rest_api.rhtml b/tracks/app/views/integrations/rest_api.rhtml new file mode 100644 index 00000000..da6177d2 --- /dev/null +++ b/tracks/app/views/integrations/rest_api.rhtml @@ -0,0 +1,218 @@ +

      REST API Documentation for Developers

      + +

      Introduction

      + +

      Tracks is designed to be integrated with scripts, web services, and third-party applications. This page serves as the documentation of our REST API.

      + +

      Tracks REST API

      + +

      The Tracks REST API allows developers to integrate Tracks into their applications. It allows applications to access and modify Tracks data, and is implemented as Vanilla XML over HTTP.

      + +

      The API is a RESTful service. All data is available through the API as a resource to which can be referred using a unique identifier. It responds to a number of the HTTP methods, specifically GET, PUT, POST and UPDATE, and all responses from the API are in a simple XML format encoded as UTF-8.

      + +

      Authentication

      + +

      Authentication is handled using Basic HTTP authentication. Your Tracks username and password is used as the authentication credentials for the API. Note that in Basic HTTP authentication, your password is sent in clear text. If you need a more secure authentication solution, you should configure your web server to run Tracks under HTTPS.

      + +

      Retrieving data from the API

      + +

      To retrieve data you only need to do an HTTP GET on a resource identifier. For example, if you want to get all the contexts with cURL:

      + +
      +
+  $ curl -u username:p4ssw0rd \
+      <%= home_url %>contexts.xml
+  >> <?xml version="1.0" encoding="UTF-8"?>
+  <contexts>...</contexts>
+
+
      + +

      Getting a single context:

      + +
      +
+  $ curl -u username:p4ssw0rd \
+      <%= home_url %>contexts/51.xml
+  >> <?xml version="1.0" encoding="UTF-8"?>
+  <context>...</context>
+
+
      + +

      Getting the todos within a context:

      + +
      +
+  $ curl -u username:p4ssw0rd \
+  <%= home_url %>contexts/51/todos.xml
+  >> <?xml version="1.0" encoding="UTF-8"?>
+  <todos type="array">...</todos>
+
+
      + +

      You also can apply the pattern shown above with projects instead of contexts.

      + +

      All data is available according to the following resource paths:

      + +
        +
      • /todos.xml
        • +
      • /todos/ID.xml
        • +
      • /contexts.xml
        • +
      • /contexts/ID.xml
        • +
      • /contexts/ID/todos.xml
        • +
      • /projects.xml
        • +
      • /projects/ID.xml
        • +
      • /projects/ID/todos.xml
        • +
      + +

      Writing to the API

      + +

      The API provides mechanisms for adding, updating and deleting resources using the HTTP methods PUT, POST and DELETE in combination with the content.

      + +

      Creating a new project, using curl:

      + +
      +
+$ curl -u username:p4ssw0rd \
+    -d "project[name]=Build a treehouse for the kids" \
+    <%= home_url %>projects.xml -i
+>> HTTP/1.1 201 Created
+Location: <%= home_url %>projects/65.xml
+...
+
+
      + +

      The response is an HTTP/1.1 201 Created with Location header indicating where the new project resource can be found. Now we can add a todo to this project, using curl:

      + +
      +
+$ curl -u username:p4ssw0rd \
+    -d "todo[description]=Model treehouse in SketchUp&todo[context_id]=2&todo[project_id]=65" \
+    <%= home_url %>todos.xml -i
+>> HTTP/1.1 201 Created
+Location: <%= home_url %>todos/452.xml
+...
+
+
      + +

      The response is a again an HTTP/1.1 201 Created with Location header indicating where the new todo resource can be found. Changing the todo notes, again using curl:

      + +
      +
+  $ curl -u username:p4ssw0rd -X PUT \
+      -d "todo[notes]=use maple texture" \
+      <%= home_url %>todos/452.xml -i
+  >> HTTP/1.1 200 OK
+  ...
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <todo>
+    ...
+    <description>Model treehouse in SketchUp</description>
+
+    <notes>use maple texture</notes>
+    ...
+  </todo>
+
+
      + +

      The response is an HTTP/1.1 200 OK with in the body the XML representation of the updated todo. We provide a shorcut method to toggle a todo done or undone without having to perform the update with the right field values:

      + +
      +
+  $ curl -u username:p4ssw0rd -X PUT \
+      <%= home_url %>todos/452/toggle_check.xml -i
+  >> HTTP/1.1 200 OK
+  ...
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <todo>
+    ...
+    <completed-at type=\"datetime\">2007-12-05T06:43:25Z</completed-at>
+
+    <state>completed</state>
+    ...
+  </todo>
+
+
      + + +

      If we want to delete that todo we can call its unique resource identifier (the URL) with the HTTP method DELETE, again with curl:

      + +
      +
+  $ curl -u username:p4ssw0rd -X DELETE \
+      <%= home_url %>todos/452.xml -i
+  >> HTTP/1.1 200 OK
+  ...
+
+
      + +

      The API returns an HTTP/1.1 200 OK and the todo is now deleted.

      + + +

      Dealing with the response and response status

      + + +

      All successful operations respond with a status code of 200 OK or 201 Created depending on the operation. Sometimes a list, say GET /contexts/2/todos.xml will not have any items, it will return an empty list.

      + +

      The XML for empty list responses look like this, again with curl:

      + +
      +
+$ curl -u username:p4ssw0rd \
+    <%= home_url %>contexts/2/todos.xml
+>> <?xml version="1.0" encoding="UTF-8"?>
+<nil-classes type="array"/>
+
+
+
      + +

      Consuming the API with ActiveResource

      + +

      ActiveResource is a thin but powerful wrapper around RESTful services exposed by Ruby on Rails. It will be part of Rails 2.0 but until then you can get it with gem install activeresource --source http://gems.rubyonrails.org --include-dependencies.

      + +
      +
+$ script/console 
+Loading development environment (Rails 1.2.4)
+>> class Context < ActiveResource::Base; end
+=> nil
+>> Context.site = "<%= home_url %>"
+=> "<%= home_url %>" 
+>> Context.site.user = "username" 
+=> "username" 
+
+>> Context.site.password = CGI.escape "p4ssw0rd" 
+=> "p4ssw0rd" 
+>> Context.find :first
+=> #<Context:0x262396c @prefix_options={}, @attributes={...}>
+>> >> Context.find :all
+=> [#<Context:0x274cfc8 @prefix_options={}, @attributes={...}, ...]
+
+
+
      + +

      Inspired by 37 Signals ’s Highrise wrapper, we’ve put together a small ruby wrapper (find it in the doc/ directory) for the API which sets up the ActiveResource models for you to play with in an IRB session:

      + +
      +
+$ SITE="http://username:p4ssw0rd@<%= @request.host_with_port %>" irb \
+    -r tracks_api_wrapper.rb
+
+irb(main):001:0> inbox = Tracks::Context.find :first
+irb(main):002:0> inbox.name
+=> "@inbox" 
+irb(main):003:0>
+
+
      + +

      Notes about the documentation

      + +

      A few conventions have been applied in the documentation, these are:

      + +
        +
      • ID’s in a resource URL indicate that the resource’s unique ID needs to be inserted there
        • +
      • ... indicates that unimportant bits of response data have been removed to eliminate noise from the documentation
        • +
      + +

      All examples make use of cURL .

      \ No newline at end of file diff --git a/tracks/doc/tracks_api_wrapper.rb b/tracks/doc/tracks_api_wrapper.rb index 3694556c..d52071a5 100644 --- a/tracks/doc/tracks_api_wrapper.rb +++ b/tracks/doc/tracks_api_wrapper.rb @@ -12,6 +12,25 @@ require 'activeresource' # => "my pc" # >> my_pc.todos # => [#8, "completed_at"=>Tue Apr 10 12:57:24 UTC 2007, "project_id"=>nil, "show_from"=>nil, "id"=>1432, "notes"=>nil, "description"=>"check rhino mocks bug", "due"=>Mon, 09 Apr 2007, "created_at"=>Sun Apr 08 04:56:35 UTC 2007, "state"=>"completed"}, #8, "completed_at"=>Mon Oct 10 13:10:21 UTC 2005, "project_id"=>10, "show_from"=>nil, "id"=>17, "notes"=>"fusion problem", "description"=>"Fix Client Installer", "due"=>nil, "created_at"=>Sat Oct 08 00:19:33 UTC 2005, "state"=>"completed"}] +# +# >> t = Tracks::Todo.new +# => # +# >> t.description = "do it now" +# => "do it now" +# >> t.context_id = 8 +# => 8 +# >> t.save +# => true +# >> t.reload +# => #nil, "context_id"=>8, "project_id"=>nil, "show_from"=>nil, "notes"=>nil, "id"=>1791, "description"=>"do it now", "due"=>nil, "created_at"=>Mon Dec 03 19:15:46 UTC 2007, "state"=>"active"} +# >> t.put(:toggle_check) +# => # +# >> t.reload +# => #Mon Dec 03 19:17:46 UTC 2007, "context_id"=>8, "project_id"=>nil, "show_from"=>nil, "notes"=>nil, "id"=>1791, "description"=>"do it now", "due"=>nil, "created_at"=>Mon Dec 03 19:15:46 UTC 2007, "state"=>"completed"} + +# If you want to see the HTTP requests and responses that are being passed back and +# forth, you can tweak your active_resource like as described in: +# http://blog.pepperdust.org/2007/2/13/enabling-wire-level-debug-output-for-activeresource module Tracks