API, документация

Пример запроса клиента
Привет ответа сервера
Список методов

SaveFact - сохранение или добавления факта
DeleteFact - удаление факта
GetFacts - получение списка фактов

API проекта "100 фактов обо мне" базируется на XML-RPC-протоколе, что позволяет работать c системой удаленно, из внешних программ, посредством HTTP-запросов и языка разметки XML. Используемая кодировка - UTF-8. Все спецсимволы в строковых значения должны быть экранированы в соотствествии с правилами языка разметки XML.

Клиентские программы отправляют XML-запросы с указанием метода и его параметров. При корректном заполнении необходимых переменных и успешной авторизации метод обрабатывается и возвращает требуемые данные.

Желающие поближе познакомиться с протоколом XML-RPC могут посетить официальный сайт или Википедию.

Пример запроса клиента

Клиент отправляет запрос на удаление своей записи:

POST /xmlrpc HTTP/1.0
Host: 100faktovobomne.ru
Content-Type: text/xml
User-Agent: XML-RPC Client
Content-Length: 529

<?xml version="1.0"?>
<methodCall>
<methodName>DeleteFact</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>id</name>
<value>
<string>64</string>
</value>
</member>
</struct></value>
</param>
<param>
<value>
<struct>
<member>
<name>login</name>
<value>
<string>Семиаминов Вениамин Абрамович</string>
</value>
</member>
</struct></value>
</param>
<param>
<value>
<struct>
<member>
<name>password</name>
<value>
<string>myprivatepassword</string>
</value>
</member>
</struct></value>
</param>
</params>
</methodCall>

При этом вызывается метод DeleteFact и ему передаются параметры id, login, password.

Пример ответа сервера

Сервер обработал запрос клиента и возвращает данные или статус операции.

HTTP/1.1 200 OK
Date: Fri, 17 Apr 2009 13:47:24 GMT
Server: Apache/2.2.9
Content-Length: 220
Vary: Accept-Encoding
Connection: close
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
<params>
<param>
<value>
<struct>
<member>
<name>status</name>
<value>
<string>OK</string>
</value>
</member>
</struct></value>
</param>
</params>
</methodResponse>

"ОК" в данном случае означает, что авторизационные данные верны и ошибок при выполении операции не произошло.

Методы

Желающие использовать API могут использовать следующие методы, список которых будет расширяться по мере необходимости для дублирования всего необходимого функционала.

Параметры запроса и возвращаемые объекты будут в структуре, показанной в примерах.

SaveFact

Сохранение или добавления факта.

Параметры запроса:

login - логин пользователя в системе, строка
password - пароль пользователя в системе, строка
id - уникальный номер существующего факта (если нужно сохранить, а не добавлять), число
title - название факта, строка
description - описание факта, строка
tags - теги через запятую, строка
status - 1, если вы оцениваете факт как отрицательный, 2 - если положительный, 0 - нейтральный, число

Тело запроса будет, к примеру, таким:

<?xml version="1.0"?>
<methodCall>
<methodName>SaveFact</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>title</name>
<value>
<string>Я люблю грызть орехи</string>
</value>
</member>
</struct></value>
</param>
<param>
<value>
<struct>
<member>
<name>tags</name>
<value>
<string>еда, здоровье</string>
</value>
</member>
</struct></value>
</param>
<param>
<value>
<struct>
<member>
<name>description</name>
<value>
<string>Это здорово укрепляет мои зубы.</string>
</value>
</member>
</struct></value>
</param>
<param>
<value>
<struct>
<member>
<name>login</name>
<value>
<string>Семиаминов Вениамин Абрамович</string>
</value>
</member>
</struct></value>
</param>
<param>
<value>
<struct>
<member>
<name>password</name>
<value>
<string>myprivatepassword</string>
</value>
</member>
</struct></value>
</param>
</params>
</methodCall>

DeleteFact

Удаление факта.

Параметры запроса:

login - логин пользователя в системе, строка
password - пароль пользователя в системе, строка
id - уникальный номер существующего факта, подлежащего удалению, число

Пример тела запроса на удаление уже был приведен выше.

GetFacts

Получение списка фактов.

Параметры запроса:

login - логин пользователя в системе, строка
password - пароль пользователя в системе, строка
id - уникальный номер факта, число
tag - название тега, по которому хотите получить записи, строка
user - логин пользователя, факты которого хотите получить, строка

Параметры user и tag можно комбинировать для получения записей конкретного пользователя по конкретному тегу.

Пример тела запроса:

<?xml version="1.0"?>
<methodCall>
<methodName>GetFacts</methodName>
<params>
<param>
<value>
<struct>
<member>
<name>id</name>
<value>
<string>15</string>
</value>
</member>
</struct></value>
</param>
<param>
<value>
<struct>
<member>
<name>login</name>
<value>
<string>Семиаминов Вениамин Абрамович</string>
</value>
</member>
</struct></value>
</param>
<param>
<value>
<struct>
<member>
<name>password</name>
<value>
<string>myprivatepassword</string>
</value>
</member>
</struct></value>
</param>
</params>
</methodCall>

Запрашивается факт с номером 15 (уникальный номер в системе). Сервер отвечаются следующим блоком данных:

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
<params>
<param>
<value>
<array>
<data>
<value>
<struct>
<member>
<name>id</name>
<value>
<string>15</string>
</value>
</member>
<member>
<name>user</name>
<value>
<string>Семиаминов Вениамин Абрамович</string>
</value>
</member>
<member>
<name>title</name>
<value>
<string>Я люблю грызть орехи</string>
</value>
</member>
<member>
<name>description</name>
<value>
<string>Это здорово укрепляет мои зубы.</string>
</value>
</member>
<member>
<name>date</name>
<value>
<string>2009-03-23 14:51:41</string>
</value>
</member>
<member>
<name>num</name>
<value>
<string>12</string>
</value>
</member>
</struct></value>
</data>
</array>
</value>
</param>
</params>
</methodResponse>