Методы REST API
Адрес: http://api.apelsinki.com/api/v1/{method}. Общие параметры: application_key, session_key (или uid при серверной подписи), sig, необязательный callback.
| Метод | Право | Параметры / описание |
|---|
users.getCurrentUser | — | данные текущего пользователя (viewer) | users.getInfo | 1 | данные пользователей по списку uids (до 100) | users.isAppUser | — | установил ли текущий пользователь приложение | users.hasPermission | — | есть ли у приложения право (permission) от пользователя | friends.get | 32 | id друзей текущего пользователя | friends.getAppUsers | — | id друзей, у которых установлено приложение | friends.getOnline | 32 | id друзей, которые сейчас на сайте | photos.getAlbums | 2 | альбомы пользователя | photos.get | 2 | фотографии альбома (aid), до 100 | photos.getProfile | 2 | текущее главное фото пользователя (pid, размеры, download_url) | photos.upload | 2 | загрузить JPG/PNG/GIF (POST multipart, поле photo, до 8 МБ) в альбом приложения; caption — подпись | storage.get | — | значения ключей (keys, через запятую) для текущего пользователя; global=1 — общие | storage.set | — | записать key=value (до 64 символов ключ, 64 КБ значение) | storage.delete | — | удалить key | stream.publish | 16 | опубликовать запись (message, url) в ленту пользователя | status.set | 8 | установить статус (text) | notifications.sendInvite | — | пригласить друзей (uids, text) — лимит в сутки | events.log | — | достижение в игре (text) → событие ленты «достижение в игре» | payment.create | — | создать платёж (amount, product_code, product_name) → payment_id и url окна оплаты | payment.status | —
серверный | статус платежа (payment_id): 0 ожидает, 1 оплачен, 2 отменён, 3 колбэк доставлен | app.getUsersCount | —
серверный | число установивших приложение |
Формат пользователя
{"uid": 42, "first_name": "Игорь", "last_name": "Ганюков", "name": "Игорь Ганюков", "sex": "male", "age": 35, "city": "Курск", "country": "Россия",
"pic_50": "…_s.jpg", "pic_110": "…_a.jpg", "pic_180": "…_m.jpg", "online": true, "url": "http://apelsinki.com/profile/42"}
Фотографии
Нужно право PHOTO_CONTENT (код 2). Все методы работают от имени текущего пользователя: session_key из браузера или uid при серверной подписи.
| Метод | Параметры | Ответ |
|---|
photos.getAlbums | — | список альбомов: aid, title, count, cover |
photos.get | aid — альбом | до 100 фото альбома в формате фото (ниже) |
photos.getProfile | — | текущее главное фото пользователя в формате фото или null, если его нет |
photos.upload | POST multipart/form-data: файл в поле photo (JPG, PNG или GIF, до 8 МБ), необязательно caption — подпись до 500 символов | загруженное фото в формате фото; кладётся в альбом пользователя с названием приложения (альбом создаётся сам). Не больше 30 загрузок в час на пользователя |
Формат фото
// aid — в photos.getProfile и photos.upload, caption — в photos.get
{"pid": 19, "aid": 7, "caption": "На даче",
"pic_50": "…_s.jpg", "pic_180": "…_m.jpg", "pic_640": "…_l.jpg", "pic_1280": "…_x.jpg",
"width": 1280, "height": 960,
"download_url": "http://api.apelsinki.com/api/v1/photo/19/5/1790990000/3f2a….jpg"}
pic_* — адреса для показа в браузере пользователя: картинки отдаются только вошедшим на сайт, поэтому сервер приложения их скачать не сможет.
Чтобы обработать фото на своём сервере (рамка, коллаж), берите download_url: это фото 1280 px, ссылка подписана сайтом, работает без входа и живёт 1 час — потом запросите фото заново.
Загрузка: что подписывать
Подпись sig считается как обычно — по всем текстовым полям запроса, кроме sig. Сам файл photo в подписи не участвует.
# с сервера приложения (серверная подпись, uid — кому загрузить)
# sig = md5("application_key=K" + "caption=Моя рамка" + "uid=42" + application_secret)
# поля по алфавиту, файл photo не входит
curl -F "application_key=K" -F "uid=42" -F "caption=Моя рамка" -F "sig=…" -F "photo=@frame.jpg" \
http://api.apelsinki.com/api/v1/photos.upload
=> {"response": {"pid": 120, "aid": 31, "pic_640": "…", "download_url": "…"}}
Ошибки: NO_FILE — нет файла в поле photo; BAD_FILE — не картинка или больше 8 МБ (текст причины в msg); LIMIT — больше 30 загрузок за час.
Сделать фото главным
Сменить главное фото пользователя через API нельзя — это решает только сам пользователь. В браузере вызовите SVAPP.setProfilePhoto(pid, cb) (см. «Клиентская библиотека»): сайт откроет окно с этим фото и кнопками «Сделать главным» / «Отмена».
Хранилище
storage.set пишет данные текущего пользователя (счёт, прогресс). С global=1 — общие данные приложения (таблица рекордов); писать их может только сервер приложения (серверная подпись) или владелец.
Примеры
# друзья, у которых есть приложение
GET /api/v1/friends.getAppUsers?application_key=K&session_key=S&sig=… => {"response":[7,15,203]}
# записать прогресс
POST /api/v1/storage.set key=level value=12 application_key=K session_key=S sig=… => {"response":true}
# серверный вызов: сколько пользователей
GET /api/v1/app.getUsersCount?application_key=K&sig=md5("application_key=K"+application_secret)
|