API управління ставками. Документація для розробників

Опис і загальні принципи використання

API спроектовано, слідуючи архітектурному стилю REST. Це означає, що для вказівки дії над ресурсом використовуються HTTP-методи. Підтримуються 4 методу: GET, POST, PUT, DELETE.

GET – отримати дані PUT | POST – створити / відредагувати DELETE – видалити

Якщо немає можливості посилати, або не підтримуються PUT | DELETE запити, видалення можна провести за допомогою запиту
GET з параметром action = delete (GET /bids/123/?action = delete)

API підтримує версійність. Номер версії вказується при кожному запиті, наприклад: GET /api/v1/{resource}

Підтримуваний формат – json.

Необхідні параметри:

– Auth_token string, 32 symbols – доступний на сторінці «Аукціонні місця» акаунта магазину.

Коди помилок:

• 400 – Bad request. Непідтримуваний запит, неправильно сформований запит
• 403 – Unauthorized. Неправильний або не переданий авторизаційний ключ
• 404 – Not found. Не знайдено ресурс, що не передані обов'язкові параметри
• 500 – Internal server error.

Коди успішної обробки запиту:

200 – Success. Успішне отримання даних, видалення
201 – Created. Запис створена, відредагована

Як потестувати?

Є безліч REST-клієнтів. Для тестування GET запитів досить браузера, для інших типів запитів можна використовувати cURL.

Приклад повноцінного GET-запиту з використанням адресного рядка браузера:

    https://hotline.ua/api/v1/bids/?auth_token=1cf0ce29cd69f536959ff98bddb0a237
    

Приклад запиту для зміни ставки з використанням cURL:

    curl -X PUT 'https://hotline.ua/api/v1/bids/offers/48?cost=460&auth_token=1cf0ce29cd69f536959ff98bddb0a237'
    

Приклад запиту для імпорту ставок з використанням cURL:

    curl -X POST -H 'Content-Type: application/json' -d '{"bids": [{"firm_offer_id": 1001, "cost": 600}]}' 'https://hotline.ua/api/v1/bids/?auth_token=1cf0ce29cd69f536959ff98bddb0a237'
    

Основні ресурси і приклади викликів

bids

Приклади і опис викликів

GET / bids / offers – отримати список встановлених ставок по товарах

Приклад відповіді:

    [
       {
          "cost": "500",
          "firm_offer_id": "1001"
            },
       {
          "cost": "220",
          "firm_offer_id": "1101"
            },
       {
          "cost": "340",
          "firm_offer_id": "1003"
            }
    ]
    

• GET /bids/offers/{firmOfferId} – отримати встановлену ставку по ID пропозиції фірми.
• firmOfferId – унікальний номер товару в базі даних фірми, який передається нам у файлі товарного фіду в поле <id>.
• GET / bids / offers/{firmOfferId}/advices – отримати список ставок
• GET /bids/offers/{firmOfferId}/advices/{place} – отримати значення ставки для потрапляння на вказане місце
• GET /bids/offers/advices?firm_offer_id = id1, id2, id3 – отримати список ставок по зазначеному списку товарів
• GET /bids/offers/advices?firm_offer_id = [{"firm_offer_id": "{id1}", "place": "{place1}"}, {"firm_offer_id": "{id2}", "place": "{place2}"] – отримати список ставок по зазначеному списку товарів і місцем для кожного

Максимальний розмір GET-запиту – 8 кілобайт.

Опис викликів далі аналогічно попереднім і є самодокументуємим.

• DELETE /bids
• DELETE /bids/offers
• DELETE /bids/offers/{firmOfferId}

Запити для створення/редагування:

Для запитів створення/редагування, як тіла запиту повинна бути використана json-рядок c встановленим заголовком

        Content-Type: application/json
    

PUT | POST / bids Тіло запиту: {"bids":[{"firm_offer_id": 1001, "cost": 610}]}

При одиночній установці ставок обов'язковим параметром є cost (int, значення ставки в центах):

PUT | POST /bids/offers/{firmOfferId}?cost = {cost}