Версія 0.91 опублікована 20.10.2011

Цей документ описує API для роботи з контентом УкрБашу в зручних для автоматичної обробки форматах (JSON та XML). Доступ до API УкрБашу є відкритим для усіх зареєстрованих користувачів, потрібно лише отримати API ключ.

Розробка першої версії API фокусувалась лише на отриманні контенту. Зараз йде робота над другою версією API в якій з’явиться авторизація, голосування та додавання нового контенту (цитат та картинок).

Це API розроблялося з розрахунком на активне використання але не варто забувати про кешування на клієнті (особливо це стосується програм для мобільних телефонів). Якщо клієнт буде генерувати занадто велику кількість запитів то його IP адреса буде тимчасово заблокована.

Технічна інформація викладена в лаконічному вигляді але її має бути достатньо щоб зрозуміти як працює API. Якщо коротко, то для отримання інформації з УкрБашу потрібно відправити HTTP запит на спеціально адресу.

Приклади запитів. З часом кількість прикладів буде збільшуватись.

Повідомлення про помилки та пропозиції надсилайте сюди: ukrbash[пес]ukrbash.org з відповідною темою (для прикладу: «помилка в роботі API»)

• 0.91 - 20.10.2011 - Додані ресурси users.*
• 0.90 - 08.10.2011 - Перший публічний реліз

• https://api.ukrbash.org/1/розділ.ресурс.формат?параметри

• quotes.getPublished // опубліковані цитати
• quotes.getUpcoming // неопубліковані цитати
• quotes.getTheBest // найкращі цитати
• quotes.getRandom // випадкові цитати
• quotes.getByID // пошук цитат за ID (лише id та limit)
• pictures.getPublished // опубліковані картинки
• pictures.getUpcoming // неопубліковані картинки
• pictures.getTheBest // найкращі картинки
• pictures.getRandom // випадкові картинки
• pictures.getByID // пошук картинок за ID (лише id та limit)
• users.getList // список користувачів форуму (лише start та limit)
• users.getByID // пошук користувачів за ID (лише id, start та limit)
• site.getInfo // загальна статистика (параметрів немає)
• site.getTags // список теґів (параметрів немає)
• site.getSearch // пошук цитат та картинок (лише query, start та limit)

• json, xml, debug // якщо запит неможливо розібрати — помилка видається в форматі xml

• client // API ключ, обов’язковий
• start // 0
• limit // 25, максимум 500
• addBefore // додано перед, unixtime (<=)
• addAfter // додано після, unixtime (>=)
• pubBefore // опубліковано перед, unixtime (<=)
• pubAfter // опубліковано після, unixtime (>=)
• withAuthor // ID автора, withAuthor=10 або withAuthor[]=0&withAuthor[]=1
• withoutAuthor // ID автора, withoutAuthor=10 або withoutAuthor[]=0&withoutAuthor[]=1
• // якщо є withAuthor то ігнорується withoutAuthor
• withTag // withTag=5 або withTag[]=1&withTag[]=10
• withoutTag // withoutTag=5 або withoutTag[]=1&withoutTag[]=10
• // якщо є withTag то ігнорується withoutTag
• query // пошук за текcтом цитати, назвою картинки або ніком автора (>= 3 символа)
• stats // якщо true то до відповіді додається загальна статистика сайту (site.getInfo)
• safe_only // якщо true то ігнорується контент, що має мітку NSFW
• column // column=status або column[]=status&column[]=rating (показ певних полів)
• id // id=100 або id[]=100&id[]=101 (пошук за ID, працює лише в getByID)

• Accept-Encoding: gzip // відповідь буде запакована gzip (DEFLATE)

quotes.*

• id // ID цитати
• status // 1 – неопублікована, 2 — опублікована, 0 — видалена
• type // quote
• add_date // дата додавання, unixtime
• pub_date // дата публікації, unixtime, 0 якщо status=1
• author // login або анонім
• author_id // ID автора, 0 якщо анонім
• text // текст цитати
• rating // рейтинг
• tags // масив теґів
•      tag // ID та назва теґу

pictures.*

• id // ID картинки
• status // 1 – неопублікована, 2 — опублікована, 0 — видалена
• type // picture
• add_date // дата додавання, unix time
• pub_date // дата публікації, unix time, 0 якщо status=1
• author // login або анонім
• author_id // ID автора, 0 якщо анонім
• image // картинка 400х400
• thumbnail // картинка 150х150
• title // назва картинки
• rating // рейтинг
• // теґів в картинок поки немає

users.*

• id // ID користувача
• name // ім’я/логін
• group // група (Адміністратори, Модератори, Користувачі)
• joined // дата реєстрації, unix time
• karma // «карма»
• quotes_all // доданих цитат
• quotes_pub // опублікованих цитат
• pictures_all // доданих картинок
• pictures_pub // опублікованих картинок

site.getInfo

• quotes_published // опублікованих цитат
• quotes_upcoming // неопублікованих цитат (за останній місяць)
• quotes_published_today // опублікованих цитат сьогодні
• quotes_upcoming_today // доданих цитат сьогодні
• pictures_published // опублікованих картинок
• pictures_upcoming // неопублікованих картинок (за останній місяць)
• pictures_published_today // опублікованих картинок сьогодні
• pictures_upcoming_today // доданих картинок сьогодні
• users // зареєстровано користувачів
• mood // «Настрій дня»

site.getTags

• id // ID теґу
• name // назва теґу
• url // теґ для url
• quotes // кількість опублікованих цитат з цим теґом

помилки

• code // код помилки
• text // текстове пояснення (українською)
• url // адреса, за якою був виконаний запит

• https://api.ukrbash.org/1/quotes.getPublished.json?client=ключ
• https://api.ukrbash.org/1/quotes.getUpcoming.json?client=ключ
• https://api.ukrbash.org/1/quotes.getTheBest.json?client=ключ
• https://api.ukrbash.org/1/quotes.getRandom.json?client=ключ
• https://api.ukrbash.org/1/quotes.getByID.json?id=17726&client=ключ
• https://api.ukrbash.org/1/pictures.getPublished.json?client=ключ
• https://api.ukrbash.org/1/pictures.getUpcoming.json?client=ключ
• https://api.ukrbash.org/1/pictures.getTheBest.json?client=ключ
• https://api.ukrbash.org/1/pictures.getRandom.json?client=ключ
• https://api.ukrbash.org/1/pictures.getByID.json?id=113&client=ключ
• https://api.ukrbash.org/1/users.getList.json?client=ключ
• https://api.ukrbash.org/1/users.getByID.json?id=1&client=ключ
• https://api.ukrbash.org/1/site.getInfo.json?client=ключ
• https://api.ukrbash.org/1/site.getTags.json?client=ключ
• https://api.ukrbash.org/1/site.getSearch.json?query=mrgall&client=ключ

• 400 Неправильний запит
• 401 Відсутній API ключ
• 403 API ключ не існує або заблокований
• 404 Нічого не знайдено
• 405 Метод не реалізований
• 410 Метод застарів (для stats.*)
• 418 Пошуковий запит має містити щонайменше 3 символи
• 503 Сервіс недоступний