~~META:title=TheWord Web Services~~

===== Web Services in /service/TheWord/ =====

Basepath for all service URLs is http:%%//%%bible2.net/service/TheWord/

===== Resource twd11 =====

^  Method ^ URL fragment ^ Parameter ^ Side-effect,  Response ^
| GET | ''twd11/'' [[http://bible2.net/service/TheWord/twd11/?format=csv|example]] | ''format=csv'' | See [[#Format of CSV List]] |
| | ''twd11/'' [[http://bible2.net/service/TheWord/twd11/?format=atom|example]] | ''format=atom'' | Feed with files, see [[#Atom List]] |
| | ''twd11/'' [[http://bible2.net/service/TheWord/twd11/|example]] | ''format=html'' (default) | XHTML 1.0 table, see [[#HTML List]] |
| GET | ''twd11/current'' | ditto | Same as ''twd11/'', but only files of current year and years to come |
| GET | ''twd11/archive'' | ditto | Same as ''twd11/'', but only files of past years |
| GET | ''twd11/$lang_$bible_$year'' | ''format=twd'' | delivers ''.twd'' file |
| | ''twd11/$lang_$bible_$year.twd'' | | same as ''format=twd'' |


===== Format of CSV List =====

Example:
<code>
category;year;lang;bible;biblename;updated;url;info
file;2009;de;Schlachter2000;Schlachter 2000;2008-09-02T20:20:56+02:00;http://bible2.net/service/TheWord/twd11/de_Schlachter2000_2009.twd;
file;2008;de;Schlachter2000;Schlachter 2000;2008-09-02T20:20:56+02:00;http://bible2.net/service/TheWord/twd11/de_Schlachter2000_2008.twd;
file;2007;de;Schlachter2000;Schlachter 2000;2008-09-02T20:20:56+02:00;http://bible2.net/service/TheWord/twd11/de_Schlachter2000_2007.twd;</code>

  * The file starts with a header line.
  * The order of columns is not guaranteed - **use the header names** to find the column index of a specific column.
  * The structure of the following lines depends on the value of the first cell („category") of the respective line.
  * The list is sorted descending by 1. year, 2. „updated".


==== Categories ====
^ Category ^ Structure of line (columns) ^
| info | cell in „info" column is information to be displayed to the user, see [[#Columns for category „info"]] |
| file | cells in the following columns are specified by the header line, see [[#Columns for category „file"]] |


==== Columns for category „info“ ====
^ Column ^ Description ^
| info | information to be displayed to the user, newlines are written as ''\n'' (two characters), no semi-colon contained. |
| updated | date of last modification of this info item (ISO format) |
| lang | language of the info text (at least a line with lang="en" will be available) |


==== Columns for category „file“ ====
^ Column ^ Description ^
| year | 4-digit year number |
| lang |ISO language code|
| bible | short name (A-Za-z0-9) of Bible, e.g. ''Schlachter2000'' |
| biblename | name of Bible, e.g. ''Schlachter 2000'' (Unicode characters) |
| updated |date of last modification of the ''.twd'' file (ISO format) |
| url | URL to retrieve the ''.twd'' file. e.g. ''http:%%//%%bible20.local/service/TheWord/twd11/de_Schlachter2000_2009.twd'' \\ Note: the URL is meant to be used as is. **Its format may change** (e.g. whether a query part ''?...'' is used or not).\\ **Its value may change** - do not publish the URL value, use the API to retrieve the URL. |
| info | info about the last modification, other important info about the file. Newlines are written as „\n" (two characters), no semi-colon contained. |


===== Atom List =====
Feed with multiple entries. Each entry has one of the categories listed above for ''.csv''.

The list is sorted descending by the field ''updated''.


==== Elements for category „info“ ====
^ Element ^ Description ^
| content | information to be displayed to the user. |


==== Elements for category „file“ ====
For the following, ''$year'', ''$lang'', ''$bible'', ''$biblename'' have the respective values described above for csv format.

^ Element ^ Description ^
| id | $year.$bible |
| title | $year $lang $biblename |
| link | rel='alternate': URL of .twd file for download |
| content | „info" of csv format |


=== Example ===
<code xml>
<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom' xml:lang='en'
>
<id>twd11</id>
<title>twd11</title>
<updated>2008-09-02T20:20:56+02:00</updated>
<entry>
<id>2008.Schlachter2000</id>
<title>2008 de Schlachter 2000</title>

<updated>2008-09-02T20:20:56+02:00</updated>
<link rel='alternate' href='http://bible20.local/service/TheWord/twd11/de_Schlachter2000_2008.twd'/>
<content>2008-09-02: new version<br />
2008-09-01: initial version</content>
</entry>
<entry>
<id>2007.Schlachter2000</id>
<title>2007 de Schlachter 2000</title>
<updated>2008-09-02T20:20:56+02:00</updated>
<link rel='alternate' href='http://bible20.local/service/TheWord/twd11/de_Schlachter2000_2007.twd'/>
</entry>
<entry>
<id>2009.Schlachter2000</id>
<title>2009 de Schlachter 2000</title>
<updated>2008-09-02T20:20:56+02:00</updated>
<link rel='alternate' href='http://bible20.local/service/TheWord/twd11/de_Schlachter2000_2009.twd'/>
</entry>
</feed>
</code>

===== HTML List =====
HTML page with a table containing one row per file. Each row has one of the categories listed above for  ''.csv''.

The table is sorted descending by the fields ''year'' and ''updated''.