Methods 1.1/ru
From Aviberry API
К содержанию
Возникли вопросы?
Список методов API
- startConversion
- cancelConversion
- deleteConversion
- getConversion
- getConversionCount
- getConversions
- getProgress
- getTraffic
Все методы API имеют имена в стиле camelCase, и именно в таком виде они должны быть указаны при вызове: в URL запроса для метода GET и в теле запроса для метода POST. При вызовах API по методу GET все значения параметров должны быть закодированы соответственно стандарту.
Параметры, передаваемые методам, могут быть следующих типов: строка, массив или объект. Параметры, являющиеся массивами и объектами, допускают дополнительные уровни вложенности, т.е. могут в качестве значений своих свойств иметь массивы или подобъекты. Под "объектом" здесь и далее в этом руководстве следует понимать ассоциативный массив, т.е. набор пар ключ=значение. В зависимости от протокола запроса такой "объект" должен быть представлен или как JSON-объект для JSON-RPC, или XML-структура для XML-RPC.
Все методы API, которые на входе принимают данные в разнородном виде, на выходе всегда возвращают данные в однородном виде. Так, например, если какой-либо метод принимает на входе или строковый идентификатор, или массив таких строковых идентификаторов, то на выходе метод всегда возвращает массив с одним или более элементами, представляющими требуемую информацию по соответствующем идентификаторам. Этот принцип призван упростить написание клиентского кода.
Для вызовов с помощью метода GET "объект" должен передаваться по соглашению, согласно которому в URL должно быть закодировано (придерживаясь специальной нотации) каждое свойство объекта, значение которого необходимо установить, и каждый такой элемент в этот момент выступает как отдельный параметр:
object[property]=value object[property][subproperty]=value object[property][subproperty][subsubproperty]=value и т.д.,
где символы [ и ] являются обязательными элементами синтаксиса. Далее по тексту, указания на свойства каких-либо объектов будут делаться также, придерживаясь этого синтаксиса.
Под "массивом" следует понимать обычный массив, элементы которого последовательно пронумерованы начиная с 0. В зависимости от протокола запроса такой "массив" должен быть представлен или как JSON-массив для JSON-RPC, или XML-массив для XML-RPC.
Для вызовов с помощью метода GET "массив" должен передаваться по соглашению, согласно которому в URL должен быть закодирован (придерживаясь специальной нотации, представленной ниже) каждый элемент массива, значение которого необходимо установить, и каждый такой элемент в этот момент выступает как отдельный параметр:
object[]=value // object[0] object[]=value // object[1] object[]=value // object[2] и т.д.,
где символы [ и ] являются обязательными элементами синтаксиса.
Для вызовов с помощью метода GET булево значение true может быть закодировано как '1', 'true' или 'yes'. Все остальные значения трактуются как false.
Предлагаемая реализация передачи объекта по методу GET идет в "нарушение" официальной спецификации для протокола JSON-RPC 1.1. Согласно спецификации JSON-RPC 1.1 через GET объекты не передаются вообще, но можно передать не ассоциативный одномерный массив. Для XML-RPC запросы GET не предусмотрены стандартом вообще, но оформленные описанным выше способом, будут приняты и обработаны и они. Для JSON-RPC на самом деле никакого физического "нарушения" стандарта нет, просто передаются специальным образом именуемые отдельные параметры.
Разработчики могут использовать сторонние библиотеки для вызовов Aviberry API, что освобождает их от ручного формирования тела запроса, а также обработки ответа от сервера для приведения ответа к более подходящему формату представления данных для используемого средства разработки. Ниже приведен список популярных библиотек для различных языков программирования:
Используя эти или какие-либо другие библиотеки, необходимо отправлять все запросы по методу POST, т.к. естественно, что ни одна из сторонних библиотек не знает об описанном выше соглашении для передачи параметров, являющихся объектами, по методу GET. Возможность вызова функций API по методу GET предусмотрена для общей "законченности" решения и в определенных ситуациях может быть очень полезна, т.к. отправка запроса по методу GET является самым простым и быстрым способом вызвать какой-либо метод Aviberry API, не прибегая к сторонним средствам.
