tracks/app/views/integrations/rest_api.html.erb

<h1><%= t('rest_help.title') %></h1>

<h2><%= t('rest_help.intro.title') %></h2>

<p><%= t('rest_help.intro.content') %></p>
<p><%= t('rest_help.intro.content_2') %></p>

<p><%= raw I18n.t 'rest_help.intro.content_3', restful_link: link_to(I18n.t('rest_help.intro.restful_link_text'), 'http://en.wikipedia.org/wiki/REST') %></p>

<h2><%= t('rest_help.auth.title') %></h2>

<p><%= raw I18n.t 'rest_help.auth.content', auth_link: link_to(I18n.t('rest_help.auth.basic_auth_link_text'), 'http://en.wikipedia.org/wiki/Basic_authentication') %></p>

<h2><%= t('rest_help.retrieve.title') %></h2>

<p><%= raw I18n.t 'rest_help.retrieve.content', curl_link: link_to(I18n.t('rest_help.curl_link_text'), 'http://en.wikipedia.org/wiki/CURL') %></p>

<pre>
<code>
  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
      <%= root_url %>contexts.xml
  &gt;&gt; &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;contexts&gt;...&lt;/contexts&gt;
</code>
</pre>

<p><%= t('rest_help.retrieve.single_context') %></p>

<pre>
<code>
  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
      <%= root_url %>contexts/51.xml
  &gt;&gt; &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;context&gt;...&lt;/context&gt;
</code>
</pre>

<p><%= t('rest_help.retrieve.todos_from_context') %></p>

<pre>
<code>
  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
  <%= root_url %>contexts/51/todos.xml
  &gt;&gt; &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;todos type="array"&gt;...&lt;/todos&gt;
</code>
</pre>

<p><%= t('rest_help.retrieve.projects') %></p>
<p><%= t('rest_help.retrieve.paths_title') %></p>

<ul>
  <li>/todos.xml</li>
  <li>/todos/done.xml</li>
  <li>/todos/<code><%= t('rest_help.id') %></code>.xml</li>
  <li>/tickler.xml</li>
  <li>/hidden.xml</li>
  <li>/calendar.xml</li>
  <li>/contexts.xml</li>
  <li>/contexts/<code><%= t('rest_help.id') %></code>.xml</li>
  <li>/contexts/<code><%= t('rest_help.id') %></code>/todos.xml</li>
  <li>/projects.xml</li>
  <li>/projects/<code><%= t('rest_help.id') %></code>.xml</li>
  <li>/projects/<code><%= t('rest_help.id') %></code>/todos.xml</li>
</ul>

<p><%= raw t('rest_help.retrieve.limit',
  fields: '<code>ID, created_at, modified_at, completed_at</code>',
  limit_parameter: '<code>limit_fields</code>',
  set_to: '<code>index</code>') %></p>

<pre>
<code>
  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
  <%= root_url %>tickler.xml?limit_fields=index
</code>
</pre>

<p><%= raw t('rest_help.retrieve.active_todos', active_code: '<code>limit_to_active_todos</code>') %></p>

<pre>
<code>
  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
  <%= root_url %>todos.xml?limit_to_active_todos=1
</code>
</pre>

<h2><%= t('rest_help.writing.title') %></h2>

<p><%= raw t('rest_help.writing.description',
  put: '<code>PUT</code>',
  post: '<code>POST</code>',
  delete: '<code>DELETE</code>') %></p>

<p><%= t('rest_help.writing.example_title') %></p>

<pre>
<code>
$ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
    -d "&lt;project&gt;&lt;name&gt;<%= t('rest_help.writing.example_project_name') %>&lt;/name&gt;&lt;/project&gt;" \
    <%= root_url %>projects.xml -i
&gt;&gt; HTTP/1.1 201 Created
Location: <%= root_url %>projects/65.xml
...
</code>
</pre>

<p><%= raw t('rest_help.writing.example_project_response_title',
  response_code: '<code>HTTP/1.1 201 Created</code>',
  header: '<code>Location</code>') %></p>

<pre>
<code>
$ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
    -d "&lt;todo&gt;&lt;description&gt;<%= t('rest_help.writing.example_todo_name') %>&lt;/description&gt;&lt;context_id&gt;2&lt;/context_id&gt;&lt;project_id&gt;65&lt;/project_id&gt;&lt;/todo&gt;" \
    <%= root_url %>todos.xml -i
&gt;&gt; HTTP/1.1 201 Created
Location: <%= root_url %>todos/452.xml
...
</code>
</pre>

<p><%= raw t('rest_help.writing.example_todo_response_title',
  response_code: '<code>HTTP/1.1 201 Created</code>',
  header: '<code>Location</code>') %></p>

<pre>
<code>
  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" -X PUT \
      -d "&lt;todo&gt;&lt;notes&gt;<%= t('rest_help.writing.example_note_text') %>&lt;/notes&gt;&lt;/todos&gt;" \
      <%= root_url %>todos/452.xml -i
  &gt;&gt; HTTP/1.1 200 OK
  ...

  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;todo&gt;
    ...
    &lt;description&gt;<%= t('rest_help.writing.example_todo_name') %>&lt;/description&gt;

    &lt;notes&gt;<%= t('rest_help.writing.example_note_text') %>&lt;/notes&gt;
    ...
  &lt;/todo&gt;
</code>
</pre>

<p><%= raw t('rest_help.writing.example_note_response_title',
  response_code: '<code>HTTP/1.1 200 OK</code>') %></p>

<pre>
<code>
  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" -X PUT \
      <%= root_url %>todos/452/toggle_check.xml -i
  &gt;&gt; HTTP/1.1 200 OK
  ...

  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;todo&gt;
    ...
    &lt;completed-at type=\"datetime\"&gt;2007-12-05T06:43:25Z&lt;/completed-at&gt;

    &lt;state&gt;completed&lt;/state&gt;
    ...
  &lt;/todo&gt;
</code>
</pre>

<p><%= raw t('rest_help.writing.example_delete_title',
  delete: '<code>DELETE</code>') %></p>

<pre>
<code>
  $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" -X DELETE \
      <%= root_url %>todos/452.xml -i
  &gt;&gt; HTTP/1.1 200 OK
  ...
</code>
</pre>

<p><%= raw t('rest_help.writing.example_delete_response_title',
  response_code: '<code>HTTP/1.1 200 OK</code>') %></p>

<h2><%= t('rest_help.response.title') %></h2>

<p><%= raw t('rest_help.response.description',
  response_200: '<code>200 OK</code>',
  response_201: '<code>201 Created</code>',
  example_call: '<code>GET /contexts/2/todos.xml</code>') %></p>

<p><%= t('rest_help.response.xml_description') %></p>

<pre>
<code>
$ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
    <%= root_url %>contexts/2/todos.xml
&gt;&gt; &lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;nil-classes type="array"/&gt;

</code>
</pre>

<h2><%= t('rest_help.activeresource.title') %></h2>

<p><%= raw I18n.t 'rest_help.activeresource.description',
  activeresource_link: link_to(I18n.t('rest_help.activeresource.activeresource_link_text'), 'http://weblog.rubyonrails.org/2007/9/30/rails-2-0-0-preview-release'),
  ror_link: link_to(I18n.t('rest_help.activeresource.ror_link_text'), 'http://www.rubyonrails.org'),
  gem_command: '<code>gem install activeresource --source http://gems.rubyonrails.org --include-dependencies</code>'
%></p>

<pre>
<code>
$ script/console
Loading development environment (Rails 1.2.4)
&gt;&gt; class Context &lt; ActiveResource::Base; end
=&gt; nil
&gt;&gt; Context.site = "<%= root_url %>"
=&gt; "<%= root_url %>"
&gt;&gt; Context.site.user = "username"
=&gt; "username"

&gt;&gt; Context.site.password = CGI.escape "p4ssw0rd"
=&gt; "p4ssw0rd"
&gt;&gt; Context.find :first
=&gt; #&lt;Context:0x262396c @prefix_options={}, @attributes={...}&gt;
&gt;&gt; &gt;&gt; Context.find :all
=&gt; [#&lt;Context:0x274cfc8 @prefix_options={}, @attributes={...}, ...]
</code>
</pre>

<p><%= raw I18n.t 'rest_help.activeresource.wrapper_description',
  signals_link: link_to(I18n.t('rest_help.activeresource.signals_link_text'), 'http://www.37signals.com') %></p>

<pre>
<code>
$ SITE="http://username:p4ssw0rd@<%= request.host_with_port %>" irb \
    -r tracks_api_wrapper.rb

irb(main):001:0&gt; inbox = Tracks::Context.find :first
irb(main):002:0&gt; inbox.name
=&gt; "@inbox"
irb(main):003:0&gt;
</code>
</pre>

<h2><%= t('rest_help.notes.title') %></h2>

<p><%= t('rest_help.notes.description') %></p>

<ul>
  <li><%= raw I18n.t 'rest_help.notes.bullet1',
    id: '<code>ID</code>',
    url: '<span class="caps">URL</span>' %></li>
  <li><%= raw I18n.t 'rest_help.notes.bullet2',
    omit: '<code>...</code>' %></li>
</ul>

<p><%= raw I18n.t 'rest_help.notes.curl_description',
  curl: link_to(I18n.t('rest_help.curl_link_text'), 'http://en.wikipedia.org/wiki/CURL') %></p>
</div>