diff --git a/app/views/integrations/rest_api.html.erb b/app/views/integrations/rest_api.html.erb index e123b00e..abf9a758 100644 --- a/app/views/integrations/rest_api.html.erb +++ b/app/views/integrations/rest_api.html.erb @@ -1,22 +1,19 @@ -

REST API Documentation for Developers

+

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

-

Introduction

+

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

-

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

+

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

+

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

-

Tracks REST API

+

<%= 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') %>

-

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.

+

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

-

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.

+

<%= 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') %>

-

Authentication

+

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

-

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:

+

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

 
@@ -27,7 +24,7 @@
-

Getting a single context:

+

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

 
@@ -38,7 +35,7 @@
-

Getting the todos within a context:

+

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

 
@@ -49,28 +46,28 @@
-

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

- -

All data is available according to the following resource paths:

+

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

+

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

-

For the todo resources (todos, tickler, done, hidden and calendar) you can limit the returned -field to ID, created_at, modified_at, completed_at by adding the parameter -limit_fields and setting it to index. For example:

+

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

 
@@ -79,7 +76,7 @@ field to ID, created_at, modified_at, completed_at by adding the pa
-If you only want to get the active todos, you add the parameter limit_to_active_todos and set it to some value like this: +

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

 
@@ -88,16 +85,19 @@ If you only want to get the active todos, you add the parameter limit_to_a
-

Writing to the API

+

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

-

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

+

<%= raw t('rest_help.writing.description', { + put: 'PUT', + post: 'POST', + delete: 'DELETE'}) %>

-

Creating a new project, using curl:

+

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

 
 $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
-    -d "<project><name>Build a treehouse for the kids</name></project>" \
+    -d "<project><name><%= t('rest_help.writing.example_project_name') %></name></project>" \
     <%= root_url %>projects.xml -i
 >> HTTP/1.1 201 Created
 Location: <%= root_url %>projects/65.xml
@@ -105,12 +105,14 @@ Location: <%= root_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:

+

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

 
 $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
-    -d "<todo><description>Model treehouse in SketchUp</description><context_id>2</context_id><project_id>65</project_id></todo>" \
+    -d "<todo><description><%= t('rest_help.writing.example_todo_name') %></description><context_id>2</context_id><project_id>65</project_id></todo>" \
     <%= root_url %>todos.xml -i
 >> HTTP/1.1 201 Created
 Location: <%= root_url %>todos/452.xml
@@ -118,12 +120,14 @@ Location: <%= root_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:

+

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

 
   $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" -X PUT \
-      -d "<todo><notes>use maple texture</notes></todos>" \
+      -d "<todo><notes><%= t('rest_help.writing.example_note_text') %></notes></todos>" \
       <%= root_url %>todos/452.xml -i
   >> HTTP/1.1 200 OK
   ...
@@ -131,15 +135,16 @@ Location: <%= root_url %>todos/452.xml
   <?xml version="1.0" encoding="UTF-8"?>
   <todo>
     ...
-    <description>Model treehouse in SketchUp</description>
+    <description><%= t('rest_help.writing.example_todo_name') %></description>
 
-    <notes>use maple texture</notes>
+    <notes><%= t('rest_help.writing.example_note_text') %></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:

+

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

 
@@ -159,8 +164,8 @@ Location: <%= root_url %>todos/452.xml
- -

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

+

<%= raw t('rest_help.writing.example_delete_title', { + delete: 'DELETE'}) %>

 
@@ -171,15 +176,17 @@ Location: <%= root_url %>todos/452.xml
-

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

+

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

+

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

-

Dealing with the response and response status

+

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

- -

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:

+

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

 
@@ -191,9 +198,13 @@ $ curl -u username:p4ssw0rd -H "Content-Type: text/xml" \
-

Consuming the API with ActiveResource

+

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

-

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.

+

<%= 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: 'gem install activeresource --source http://gems.rubyonrails.org --include-dependencies' +} %>

 
@@ -213,10 +224,10 @@ Loading development environment (Rails 1.2.4)
 >> >> 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:

+

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

 
@@ -230,13 +241,18 @@ irb(main):003:0>
-

Notes about the documentation

+

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

-

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

+

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

-

All examples make use of cURL .

+

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

+ diff --git a/app/views/users/index.html.erb b/app/views/users/index.html.erb index 9056c36b..819b4a16 100644 --- a/app/views/users/index.html.erb +++ b/app/views/users/index.html.erb @@ -22,7 +22,7 @@ <%= h user.login %> <%= h user.display_name %> <%= h user.email %> - <%= h user.auth_type %> + <%= t('auth_type.' + user.auth_type) %> <%= h user.open_id_url || '-' %> <%= h user.todos.size %> <%= h user.contexts.size %> diff --git a/config/locales/en.yml b/config/locales/en.yml index 0c5d4b4e..47df204d 100644 --- a/config/locales/en.yml +++ b/config/locales/en.yml @@ -9,6 +9,7 @@ en: due_style: Due style first_name: First name last_name: Last name + email: Email locale: Locale mobile_todos_per_page: Actions per page (Mobile View) refresh: Refresh interval (in minutes) @@ -1333,3 +1334,57 @@ en: zero: No %{model} found page_gap: "…" previous_label: "← Previous" + auth_type: + database: Database + rest_help: + title: REST API Documentation for Developers + id: ID + curl_link_text: cURL + intro: + title: Introduction + content: Tracks is designed to be integrated with scripts, web services, and third-party applications. This page serves as the documentation of our REST API. + content_2: 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. + content_3: The API is a %{restful_link} 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. + restful_link_text: RESTful + auth: + title: Authentication + content: Authentication is handled using %{auth_link}. 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. + basic_auth_link_text: Basic HTTP authentication + retrieve: + title: Retrieving data from the API + content: '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_link}:' + single_context: 'Getting a single context:' + todos_from_context: 'Getting the todos within a context:' + projects: You also can apply the pattern shown above with projects instead of contexts. + paths_title: 'All data is available according to the following resource paths:' + limit: 'For the todo resources (todos, tickler, done, hidden and calendar) you can limit the returnedfield to %{fields} by adding the parameter %{limit_parameter} and setting it to %{set_to}. For example:' + active_todos: 'If you only want to get the active todos, you add the parameter %{active_code} and set it to some value like this:' + writing: + title: Writing to the API + description: The API provides mechanisms for adding, updating and deleting resources using the HTTP methods %{put}, %{post} and %{delete} in combination with the content. + example_title: 'Creating a new project, using curl:' + example_project_name: Build a treehouse for the kids + example_project_response_title: 'The response is an %{response_code} with %{header} header indicating where the new project resource can be found. Now we can add a todo to this project, using curl:' + example_todo_name: Model treehouse in SketchUp + example_todo_response_title: 'The response is a again an %{response_code} with %{header} header indicating where the new todo resource can be found. Changing the todo notes, again using curl:' + example_note_text: use maple texture + example_note_response_title: 'The response is an %{response_code} 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:' + example_delete_title: 'If we want to delete that todo we can call its unique resource identifier (the URL) with the HTTP method %{delete}, again with curl:' + example_delete_response_title: The API returns an %{response_code} and the todo is now deleted. + response: + title: Dealing with the response and response status + description: All successful operations respond with a status code of %{response_200} or %{response_201} depending on the operation. Sometimes a list, say %{example_call} will not have any items, it will return an empty list. + xml_description: 'The XML for empty list responses look like this, again with curl:' + activeresource: + title: Consuming the API with ActiveResource + description: '%{activeresource_link} is a thin but powerful wrapper around RESTful services exposed by %{ror_link}. It will be part of Rails 2.0 but until then you can get it with %{gem_command}.' + activeresource_link_text: ActiveResource + ror_link_text: Ruby on Rails + wrapper_description: 'Inspired by %{signals_link} ’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:' + signals_link_text: 37 Signals + notes: + title: Notes about the documentation + description: 'A few conventions have been applied in the documentation, these are:' + bullet1: '%{id}’s in a resource %{url} indicate that the resource’s unique ID needs to be inserted there' + bullet2: '%{omit} indicates that unimportant bits of response data have been removed to eliminate noise from the documentation' + curl_description: 'All examples make use of %{curl}.' diff --git a/config/locales/fi.yml b/config/locales/fi.yml index 24686aa0..a64c5c92 100644 --- a/config/locales/fi.yml +++ b/config/locales/fi.yml @@ -9,6 +9,7 @@ fi: due_style: Määräpäivän esitystapa first_name: Etunimi last_name: Sukunimi + email: Sähköpostiosoite locale: Kieli mobile_todos_per_page: Toimenpidettä sivulla (mobiilisivustolla) refresh: Päivitystiheys (minuutteina) @@ -1340,3 +1341,5 @@ fi: zero: '%{model} ei löytynyt' page_gap: "…" previous_label: "← Edellinen" + auth_type: + database: Tietokanta