Транспорт API — СпамоБорец: документация

### Navigation

- index
- next |
- previous |
- СпамоБорец: документация »
- API СпамоБорца »

# Транспорт 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/

### Navigation

- index
- next |
- previous |
- СпамоБорец: документация »
- API СпамоБорца »