Транспорт API

API СпамоБорца представляет собой набор команд, которые доступны через XML-RPC [2] и JSON-RPC [1]. В зависимости от настроек сервера, они доступны через протоколы HTTP и HTTPS.

По умолчанию, JSON-RPC over HTTP доступен через URL: http://localhost:8000/api/json/, а XML-RPC: http://localhost:8000/api/xml/.

В обоих вариантах представления API используются следующие соглашения:

  • имя команды API передается в качестве имени метода;
  • любой вызов содержит ровно один позиционный RPC-параметр, который имеет тип “хэш”, в этом параметре задаются все именованные параметры команды (некоторые из которых могут быть необязательными);
  • результатом выполнения команды является хэш, который содержит параметры возврата.

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

Например, для вызова команды sf.test с параметром a со значением 1 и параметром b со значением "abcd" мы формируем следующий вызов метода:

sf.test({ a: 1, b : "abcd"})

Данный вызов будет закодирован следующим образом для XML-RPC:

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
  <methodName>sf.test</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>a</name>
            <value>
              <i4>1</i4>
            </value>
          </member>
          <member>
            <name>b</name>
            <value>
              <string>abcd</string>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

А для JSON-RPC так:

{
     "service":null,
     "method":"sf.test",
     "id":11,
     "params":
         [
             {
                 "a":1,
                 "b":"abcd"
             }
         ]
}

Ответом сервера всегда является хэш, пусть нам должны вернуть параметр d со значением 458:

{ d : 458 }

Такой ответ в случае XML-RPC будет выглядеть следующим образом:

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>d</name>
            <value>
              <i4>458</i4>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodResponse>

А для JSON-RPC случая так:

{"result": {"d": 458}, "id": 11}

Для доступа к API можно использовать существующие библиотеки XML-RPC или JSON-RPC, а также клиенты, входящие в поставку СпамоБорца.

[1]http://json-rpc.org/
[2]http://en.wikipedia.org/wiki/XML-RPC/

Previous topic

API СпамоБорца

Next topic

Типы данных

Quick search