НЕБО Паблик

h1. API

h2. Общие сведения об API Неба

Сервер Неба поддерживает взаимодействие с внешними приложениями с использованием REST-подобного API. По сути, это же API используется для работы клиентского (браузерного) приложения Неба, что позволяет внешним приложениям реализовать все те же действия, что и пользователь в основном интерфейсе Неба.

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

Текущая версия API пока не является фиксированной. Возможны изменения в составе передаваемых данных без предварительного уведомления взаимодействующих внешних приложений. Фиксация API по разделам Неба и последующая его версионность будут реализованы в течение 2014 года.

Также помните, что на текущий момент времени "защита от дурака" в Небе равномерно распределена между клиентским и серверным приложением. Значительная часть ограничений на использование Неба (в основном, некритичных для безопасности и целостности данных) реализованы путем выбора специфической схемы организации клиентского приложения, без их дублирования на серверной части. Поэтому, перед использованием тех или иных операций желательно убедиться, что они не противоречат логике предметной области и текущего поведения Неба в целом (например, посмотрев как требуемая операция реализована в интерфейсе Неба).

h2. Аутентификация внешнего приложения

Для аутентификации пользователей применяется общепринятая для Web-приложений схема.

1. Внешнее приложение отсылает GET или POST запрос на URL @https://nebopro.ru/loging@ передавая в параметрах запроса следующие значения:

* @login@ - email зарегистрированного в Небе пользователя;

* @pass@ - его пароль

2. В ответе сервера будет находится JSON объект с @{"success": true}@ при успешной аутентификации, либо @{"success": false, "msg": "Текст с причиной, почему не удалось аутентифицировать пользователя"}@.

3. В заголовке ответа сервер проставляет cookie с именем @sessionid@, которое является сессионным ключом данного пользователя. Здесь же сервер указывает максимальный срок жизни сессии - параметр @expires@. 

!loging-sessionid.png!

Полученный @sessionid@ необходимо указывать в cookie всех последующих HTTP-запросов к серверу.

h2. Пример аутентификации с последующим получением списка пользователей в аккаунте

Пример приведен на языке python

<pre>

<code class="python">

#coding:utf-8

import urllib, urllib2  # библиотека python, которая позволяет работать с HTTP запросами

import json

def authenticate(username, password):

    u""" 

    Аутентифицирует пользователя в Небе, возвращая строку с sessionid. При неудачной попытке 

    возвращается None

    """

    # формируем параметры запроса и энкодим их, чтобы они нормально ушли как параметры GET запроса

    params = urllib.urlencode({

        'login': username,

        'pass': password

    })

    # объект запроса

    req = urllib2.Request('https://nebopro.ru/loging', params)

    # получаем ответ

    resp = urllib2.urlopen(req)

    # читаем содержимое ответа

    data = json.loads(resp.read())  

    result = None

    if data['success']:

        # чтобы не уклоняться от темы, выделим sessionid таким решительным способом

        result = unicode(resp.headers['Set-Cookie'], 'utf-8')[10:42]

    return result

def get_users(sessionid):

    u""" Возвращает JSON объект со списком пользователей """

    req = urllib2.Request('https://nebopro.ru/core/nebo-user/list')

    req.add_header('Cookie', "sessionid=" + sessionid + ';')

    resp = urllib2.urlopen(req)

    result = None

    if resp.getcode() == 200 and resp.info().type == 'application/json':

        # В некоторых случаях, в т.ч. при выполнении запроса с невалидным sessionid сервер вернет

        # ответ с типом содержимого text/html. Поэтому, при анализе ответа необходимо проверять

        # HTTP-статус ответа 200 и тип ответа application/json

        result = json.loads(resp.read())['data']

    return result

# получаем ключ доступа

sessionid = authenticate('akvarats@nebopro.ru', '*******')

# получаем список пользователей

users =  get_users(sessionid)

</code>

</pre>

Для аккаунта с одним пользователем в @users@ будет следующий список из одного объекта

<pre>

<code class="json">

[{

    "profile": {

        "status": {

            "name": "\u0420\u0430\u0431\u043e\u0442\u0430\u0435\u0442",

            "id": 3

        },

        "first_name": "akvarats@nebopro.ru",

        "last_name": "",

        "middle_name": "",

        "uid": "*******************",

        "is_active": true,

        "id": 638,

        "phone": "8 927 400 12 05",

        "is_admin": true,

        "full_name": "akvarats@nebopro.ru",

        "phone_binding": {

            "can_bind_phone": false,

            "phone_bound": false

        },

        "auth_user": {

            "id": 647

        },

        "email": "akvarats@nebopro.ru"

    },

    "cnt": {

        "itsme": true,

        "hd": false

    },

    "permissions": [{

        "chapter": null,

        "access_level": {

            "name": "\u041f\u043e\u043b\u043d\u044b\u0439",

            "id": 1

        },

        "company": {

            "name": "akvarats@nebopro.ru",

            "profiles": [],

            "id": 668

        }

    }, {

        "chapter": null,

        "access_level": {

            "name": "\u041f\u043e\u043b\u043d\u044b\u0439",

            "id": 1

        },

        "company": {

            "name": "\u041a\u043e\u043c\u043f\u0430\u043d\u0438\u044f \u0438\u0437 47 \u0440\u0435\u0433\u0438\u043e\u043d\u0430",

            "profiles": [],

            "id": 9148

        }

    }, {

        "chapter": null,

        "access_level": {

            "name": "\u041f\u043e\u043b\u043d\u044b\u0439",

            "id": 1

        },

        "company": {

            "name": "\u041a\u043e\u043c\u043f\u0430\u043d\u0438\u044f \u0438\u0437 78 \u0440\u0435\u0433\u0438\u043e\u043d\u0430",

            "profiles": [],

            "id": 9149

        }

    }],

    "user": {

        "uid": "7951d057-a19f-47d8-afdd-63d66fe85b8e",

        "user_fio": "akvarats@nebopro.ru",

        "email": "akvarats@nebopro.ru",

        "id": 728

    },

    "phone_binding": {

        "can_bind_phone": false,

        "phone_bound": false

    }

}]

</code>

</pre>