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

 

РУКОВОДСТВО ПРОГРАММИСТА

Поддержка внешних приложений

BaseRide поддерживает подключение внешних приложений через HTTPS API.

Внешние приложения имеют те же права доступа к данным, что и пользователь, зарегистрированный на BaseRide.

Для аутентификации пользователя внешнего приложения используется процедура аутентификации OAuth2.

Регистрация внешнего приложения

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

Список внешних приложений пользователя доступен только ему лично.

Для регистрации приложения, необходимо открыть список внешних приложений и добавить туда запись о внешнем приложении. Внешнему приложению будет присвоен уникальный ключ приложения и секретный код приложения.

Внешнее приложение должно иметь специальный URL перенаправления, на который будет отправлена информация о временном коде авторизации на сервере BaseRide.

Пользователь может добавлять, редактировать и удалять записи о своих внешних приложениях.

Процедура аутентификации

Начало

Для аутентификации пользователя внешнего приложения, внешнее приложение должно предложить пользователю перейти в браузере на специальный URL вида https://baseride.com/oauth2/authorize/?response_type=code&client_id=<client_id>, где <client_id> - уникальный ключ приложения, присвоенный ему при регистрации приложения.

Доступ к данному URL должен быть аутентифицирован пользователем BaseRide, либо стандартным способом, когда пользователь вводит имя и пароль через форму аутентификации (на которую он будет перенаправлен из браузера, если еще не аутентифицирован), либо по протоколу простой аутентификации (Basic Authentication). Для аутентификации пользователя по протоколу простой аутентификации запрос должен содержать заголовок:

Authorization: Basic XxXxXxXx==

где XxXxXxXx== - это закодированная с помощью Base64 строка вида username:password, где username - это имя пользователя BaseRide, а password - пароль пользователя BaseRide.

После успешной аутентификации сервер BaseRide перенаправляет браузер пользователя на URL перенаправления, указанный при регистрации приложения, добавляя к URL перенаправления параметр code=<code>, где <code> - временный код авторизации на сервере BaseRide. Временный код авторизации действует в течение 2 минут с момента его отправки с сервера BaseRide на URL перенаправления внешнего приложения.

Клиент внешнего приложения может извлечь временный код авторизации прямо из заголовка Location, анализируя результат запроса специального URL.

Сервер внешнего приложения может извлечь временный код авторизации в момент обращения к его URL перенаправления.

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

Получение токена доступа

Для получения токена доступа к серверу BaseRide внешнее приложение выполняет запрос получения токена вида https://baseride.com/oauth2/token/?callback=<callback>&client_id=<client_id>&client_secret=<client_secret>&code=<code>&grant_type=authorization_code&redirect_uri=<redirect_uri>, где <callback> - произвольное имя коллбека для формирования ответа на запрос JSONP, <client_id> - уникальный ключ приложения, <client_secret> - секретный код приложения, <code> - только что полученный временный код авторизации, а <redirect_uri> должен обязательно совпадать с URL перенаправления, заданным при регистрации приложения.

Параметры запроса могут быть переданы в параметрах запроса GET или запроса POST.

Ответом на запрос являются данные JSON или JSONP (в зависимости от того, был ли задан параметр callback) следующего вида:

     {

     access_token: "a03306150a",

     token_type: "bearer",

     expires_in: 3600,

     refresh_token: "c4cdaa0565",

     scope: ""

     }

 

где возвращаемые поля имеют следующий смысл:

 

access_token - токен доступа

token_type - тип токена, всегда bearer

expires_in - время действия токена, 3600 секунд (1 час)

refresh_token - токен обновления

scope - область действия токена, в настоящий момент не используется

 

Вместо передачи <clent_secret> в параметрах запроса это значение можно передать в заголовке Authorization, используя схему HTTPS авторизации BASIC и значение Credentials в виде <client_id>:<client_secret>, как если бы <client_id> был именем пользователя, а <client_secret> - паролем.

Получение доступа к API

Значение токена доступа (поле access_token) может быть использовано внешним приложением для получения доступа к данным пользователя. Для этого, при обращении к API сервера BaseRide, нужно будет указывать это значение одним из трех следующих способов:    

в заголовках запроса: “Authorization: BEARER <access_token>” где <access_token> - переданное значение (без кавычек), например:
"Authorization: BEARER a03306150a"     

 

в параметрах запроса POST в форме параметра bearer_token или access_token, например:

bearer_token=a03306150a или access_token=a03306150a     

в параметрах запроса GET в форме параметра bearer_token или access_token, например:
bearer_token=a03306150a или access_token=a03306150a

Время действия токена доступа указывается в поле expires_in и составляет 1 час (3600 секунд).

Область действия токена (поле scope) в настоящий момент не используется.

Обновление токена доступа

Токен доступа имеет ограниченное время действия, поэтому приложение должно периодически его обновлять.

Для обновления токена доступа используется токен обновления (поле refresh_token).

Чтобы обновить токен доступа, внешнее приложение выполняет запрос к URL обновления токена. Запрос может быть выполнен как с сервера приложения (в этом случае может быть использован секретный ключ приложения), так и из клиентской части приложения или скрипта JavaScript на странице пользователя (в этом случае для авторизации запроса на обновление используется только что устаревший токен доступа, авторизующий лишь данный запрос).

Запрос с использованием секретного ключа выглядит так:    https://baseride.com/oauth2/token/?callback=<callback>&client_id=<client_id>&client_secret=<client_secret>&grant_type=refresh_token&refresh_token=<refresh_token>.

Запрос с использованием устаревшего токена доступа выглядит так: https://baseride.com/oauth2/token/?callback=<callback>&client_id=<client_id>&grant_type=refresh_token&refresh_token=<refresh_token>&access_token=<access_token> (имя параметра access_token может быть и bearer_token).

Параметры запроса: <callback> - произвольное имя коллбека для формирования ответа на запрос JSONP, <client_id> - уникальный ключ приложения, <client_secret> - секретный код приложения, <access_token> - токен доступа, требующий обновления, а <refresh_token> - токен обновления, полученный ранее.

Формат ответа совпадает с форматом ответа на запрос получения токена, описанным ранее.

В момент выполнения запроса использованный токен обновления и токен доступа, полученный вместе с этим токеном обновления, прекращают свое существование.

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

Использование уникального ключа и секретного кода приложения

Уникальный ключ приложения может быть размещен на страницах приложения или в программном коде приложения, его содержимое не является секретным и может быть передано третьим лицам. Это возможно потому, что наряду с уникальным ключом, приложение имеет секретный код.

Секретный код приложения, напротив, должен быть известен только разработчику приложения и серверу приложения. Следует избегать размещения секретного кода на страницах или в программном коде клиентской части своего приложения (например, в мобильном приложении), видимых пользователю приложения, так как в этом случае и уникальный ключ, и секретный код могут быть легко извлечены из страницы или программного кода, а пара из уникального ключа и секретного кода приложения позволит злоумышленнику полностью имитировать запросы со стороны зарегистрированного внешнего приложения.

Для защиты от атак подобного рода приложение должно выполнять запросы на получение и обновление токена доступа, в которых используется секретный ключ приложения, только со стороны сервера приложения, размещая полученный токен доступа на странице приложения (и/или возвращая его в ответах на запросы клиентской части приложения к своему серверу) для последующего использования в запросах к API BaseRide, выполняемых с этих страниц или из клиентской части приложения.

Точка доступа к API BaseRide

Единой точной доступа к API является URL https://baseride.com/api/<версия>/

В настоящий момент единственной версией API является v2, таким образом единая точка доступа к API выглядит как https://baseride.com/api/v2/

При доступе к API нужно обязательно указывать параметр format=<формат>, где <формат> имеет значение json, xml, yaml или plist. Описание этих форматов выходит за рамки данного документа.

При обращении к единой точке доступа, API возвращает все источники данных, доступные через API: https://baseride.com/api/v2/?format=json.

Доступ к единой точке доступа открыт для неаутентифицированных пользователей.

Интерфейсные URL

Каждый источник данных имеет несколько интерфейсов (URL, префиксом которых служит единая точка доступа). Все интерфейсы одного источника данных указываются в описании источника при обращении к единой точке доступа.

Доступ к интерфейсам открыт только для аутентифицированных пользователей. При этом право доступа к группам и отдельным объектам данных регулируется в соответствии с теми же правилами, что и права доступа в административной части интерфейса пользователя BaseRide.

Каждый источник данных имеет как минимум три интерфейса: интерфейс списка данных, интерфейс отдельного объекта данных и интерфейс схемы данных.

Большинство источников данных имеет интерфейс текстового поиска данных.

Отдельные источники данных имеют дополнительные интерфейсы для доступа к дополнительным структурам данных, связанных с основным объектом интерфейса. Например, источник данных о варианте маршрута https://baseride.com/routes/route_variant/ имеет дополнительный интерфейс, по которому можно получить сразу всю геометрию варианта маршрута вместе с остановками.

Получение данных

Получение данных осуществляется посредством выполнения запроса GET к интерфейсам источника данных. Запрос обязательно должен содержать параметр format=<формат>, где <формат> имеет значение json, xml, yaml или plist.

Списки объектов и постраничный вывод

Интерфейсы списка данных и поиска данных, а также некоторые дополнительные интерфейсы, возвращающие списки данных, могут возвращать данные страницами.

Если интерфейс поддерживает постраничный возврат данных, возвращаемое значение содержит два ключа: meta и objects. Ключ objects содержит список объектов, а ключ meta содержит параметры постраничного вывода и ссылки next и previous на следующую и предыдующую страницы соответственно.

По умолчанию, на странице умещается 20 объектов. Размер и положение страницы в возвращаемом списке данных регулируется параметрами запроса limit и offset соответственно. Чтобы выключить ограничение на количество выводимых объектов, можно указать параметр limit=0.

Текстовый поиск объектов

Текстовый поиск объектов осуществляется как правило по префиксу всех текстовых и целочисленных полей объекта. Для выполнения поиска, нужно обратиться к интерфейсу поиска, передав параметр q, содержащий искомые значения, разделенные пробелами.

Детальный поиск объектов

Детальный поиск объектов (фильтрация) осуществляется согласно ограничений, накладываемых как на поля самого объекта, так и на поля связанных с ним объектов. Список полей объекта можно получить с помощью интерфейса схемы данных, имеющегося у всех источников данных.

Поля и значения, представляющие из себя условия фильтрации, передаются в виде параметров запроса. Все переданные условия фильтрации объединяются логическим оператором “И”. Таким образом, в список попадают только те объекты, для которых все переданные условия выполняются.

Если нужно ограничить список только объектами, содержащими определенное значение поля, параметр выглядит как <имя-поля>__exact=<значение>, при этом <значение> не заключается в кавычки. Суффикс __exact является необязательным.

Кроме точного совпадения, для фильтрации можно указать и другие функции фильтрации. Функция фильтрации передается с помощью суффикса, начинающегося с двух символов подчеркивания.

Список функций фильтрации:

    

 

Следует с осторожностью использовать функции __contains, __endswith и __regex для поиска, так как они могут сильно замедлить выполнение запроса.

Для фильтрации можно использовать не только поля самого объекта, но и поля объектов, которые с ним связаны.

Для ссылки на поля связанных объектов, имена полей, составляющих путь до интересующего значения, нужно соединить с помощью двойного подчеркивания. Например, чтобы найти варианты маршрута, у который наименование маршрута совпадает со строкой ‘т17’, при обращении к списку вариантов маршрутов, нужно сформировать параметр route__name__exact=т17

Получение содержимого отдельного объекта

Обращение к интерфейсу отдельного объекта данных возвращает детальное содержимое запрошенного объекта.

Запросы на изменение данных

Дополнительные заголовки и параметры

Тип запроса

Для выполнения изменения данных, выполняются запросы типа POST, PATCH и DELETE. Сервер BaseRide поддерживает только запросы типа GET и POST. Другие типы запросов необходимо передавать в дополнительном заголовке запроса X-HTTPS-Method-Override, например "X-HTTPS-Method-Override: PATCH".

Тип данных

На сервер BaseRide данные передаются в форме телезапроса. Для распознавания формата передаваемых данных следует указать его в заголовке запроса Content-Type, указывая его в форме “application/<формат>” (например "Content-Type: application/json").

Поддерживаются все форматы, перечисленные для параметра запроса format.

Передача данных в формате x-www-form-urlencoded не поддерживается!

Токен доступа

При выполнении запросов аутентификация и авторизация запроса осуществляется согласно токену доступа.

Токен доступа может быть передан в URI запроса в виде параметра, в то время как данные запроса будут переданы как телезапрос в формате, указанном в заголовке запроса Content-Type.

Например:

    

     POST /api/v2/transport/vehicle_enterprise/171/?access_token=1234567890 HTTPS/1.1

     Content-Type: application/json

     X-HTTPS-Method-Override: PATCH

    

     {“name”:”MyEnterprise”}

    

Добавление объекта

Добавление нового объекта осуществляется при помощи запроса POST, обращенного к интерфейсу списка объектов источника данных.

Содержимым тела запроса POST должна являться структура, аналогичная возвращаемому значению интерфейса отдельного объекта данных того же источника данных.

Для исключения пересечений идентификации вновь создаваемых объектов следует воздерживаться от явной передачи идентификатора объекта при создании нового объекта. В этом случае идентификатор вновь создаваемого объекта будет образован автоматически.

При успешном создании нового объекта код возврата будет 201 CREATED, а ответ на запрос будет содержать заголовок Location. Например: “Location: https://baseride.com/api/v2/transport/vehicle_park/8/” со ссылкой на вновь созданный объект.

Изменение объекта

Изменение объекта выполняется при помощи запроса PATCH, обращенного к интерфейсу отдельного объекта данных. Телом запроса является структура, аналогичная возвращаемому значению интерфейса отдельного объекта данных того же источника данных. Структура должна содержать те поля, значения которых требуется изменить. Объект, подлежащий изменению, идентифицируется по переданному URL.

Успешное выполнение изменения объекта маркируется возвратом кода 202 ACCEPTED.

Удаление объекта

Удаление объекта выполняется при помощи запроса DELETE, обращенного к интерфейсу отдельного объекта данных. Объект, подлежащий удалению, идентифицируется по переданному URL.

Успешное выполнение удаления объекта маркируется возвратом кода 204 NO CONTENT.

Коды ошибок

Ошибки, возникающие при выполнении запросов, маркируются соответствующими кодами возврата протокола HTTPS.

 

    

Параметры и пример кода на javascript/jQuery.ajax для изменения данных

Рекомендуется использовать последние версии jQuery не менее чем 1.7.

Версию jQuery можно получить, обратившись из консоли JavaScript на странице с загруженным jQuery с помощью следующего синтаксиса:

     $().jquery

 

Допустим, ранее мы уже получили объект obj путем обращения к интерфейсу API: $.ajax("https://baseride.com/api/v2/transport/vehicle_enterprise/16/?format=json&access_token=1234567890",{

     success:function(obj) {

     ...

     }

     });

 

Возвращенный объект имеет следующую структуру:

     {

     description: "",

     id: 16,

     name: "demo",

     options: [ ],

     parks: [

     "/api/v2/transport/vehicle_park/13/"

     ],

     resource_uri: "/api/v2/transport/vehicle_enterprise/16/",

     routes: [

     {

     route: "/api/v2/routes/route/55/"

     },

     {

     route: "/api/v2/routes/route/124/"

     },

     {

     route: "/api/v2/routes/route/167/"

     }

     ]

     }

 

Теперь мы хотим добавить описание объекта “Демонстрация” и изменить список маршрутов, убрав из него маршрут с идентификатором 167. Для этого мы выполним запрос типа PATCH с помощью следующего кода:

     $.ajax("https://baseride.com/api/v2/transport/vehicle_enterprise/16/?format=json&access_token=1234567890",{

     type:"POST",

     data:JSON.stringify({

     description: "Демонстрация",

     routes: [

     {

     route: "/api/v2/routes/route/55/"

     },

     {

     route: "/api/v2/routes/route/124/"

     }

     ]

     }),

     processData:false,

     contentType:'application/json',

     headers:{'X-HTTPS-Method-Override':'PATCH'},

     success:function(obj) {

     console.log('SUCCESS:',obj);

     },

     error:function(obj) {

     console.log('ERROR:',obj);

     }

     });

 

Обратите внимание, что запрос PATCH может не содержать полей, которые не меняются. Идентификация объекта, подлежащего изменению, производится через передаваемый URL.

Запрос PATCH выполняется с помощью запроса POST с дополнительным параметром заголовка 'X-HTTPS-Method-Override: PATCH’.

При выполнении запросов со страниц BaseRide, аутентификация и авторизация может производиться по контексту страницы, задаваемому django. Если же запрос производится из внешнего приложения, требуется аутентификация пользователя, выполняющего запрос, с помощью access_token по протоколу OAuth2. После аутентификации пользователя, выполняющего запрос, ему предоставляются те же права доступа, какие он мог бы получить, пользуясь административным входом на BaseRide.