====== XML API ======

WikiMatrix provides access to the Wiki infos through a simple XML API. This allows you to pull interesting data from the Matrix system to create your own customized analysis (eg. "Which are the most popular programming languages for Wikis" or "What is the most used syntax for bold").

===== Usage Conditions =====

  * If you use the data on any public website or publish the results, you need to provide a link back to WikiMatrix
  * Do not hammer our servers, cache the data you pull through the API. The data does not change frequently, pulling it once a day should be enough
  * We reserve the right to restrict or change access to the API any time
  * Give us some feedback where and how you use the API (we're curious)


===== Accessing the API =====

The API is accessed through simple HTTP requests on %%http://www.wikimatrix.org/api/*%%. Data is returned as XML.

The API calls can be restricted to certain features items or products. Those can be specified either with their internal IDs as returned in the API calls or by their real names. Multiple items or products can be given separated by plus chars. Whitespaces need to be replaced by underscores. When specifying feature items by name you need to give the item group name //and// the item name separated by a colon.

==== API URLs ====

^ API-URLs                                                       ^ Description      ^
| %%http://www.wikimatrix.org/api/byproduct/<products>%%         | List <products> with all their items |
| %%http://www.wikimatrix.org/api/byitem/<items>/<products>%%    | List <items> with the values for <products> |
| %%http://www.wikimatrix.org/api/items/<items>%%                | List <items> |
| %%http://www.wikimatrix.org/api/products/<products>%%          | List <products> |


==== Example API calls ====

^ Example Calls                                               ^ Description  |
| %%http://www.wikimatrix.org/api/byproduct%% 	              | List all products and all their features |
| %%http://www.wikimatrix.org/api/byproduct/44+DokuWiki%% 	      | List all product with ID 44 and DokuWiki with all their features |
| %%http://www.wikimatrix.org/api/byitem/General_Features:Version%% | List the version of all Products |
| %%http://www.wikimatrix.org/api/byitem/General_Features:Version/DokuWiki+MediaWiki%% | List the version of DokuWiki and MediaWiki |
| %%http://www.wikimatrix.org/api/items%%                         | Get a list of all feature items |
| %%http://www.wikimatrix.org/api/items/44%%                      | Get info about Item 44 (eg. its name) |
| %%http://www.wikimatrix.org/api/product/DokuWiki%%              | Get info about DokuWiki (eg. its ID) |

==== Error Handling ====

Errors are returned as simple XML structure with an error code and an error message. Eg:

<code xml>
<error code="12">
Can not create XML: Item name or id "foo" is unknown.
</error>
</code>