Описание стиля REST api

style_guide.rst

API style guide

За основу взято http://www.restapitutorial.com/resources.html.

Именование restful апи

• Список сущностей называется во множественном числе. Например, /categories/
• Объект сущности всегда имеет первичный ключ в ссылке. Например, /categories/1/
• Сущность, которая всегда еденична, нахывается в единственном числе. Например, shop/certificate/

• Если существует специальное взаимодействие с объектом или объектами, то добавляется метод в единственном числе. \

  Например, /categories/1/set_fav/

• Для разделения слов, если сущность имеет более чем 2 слова, используется нижнее подчеркивание. Пример: /set_fav/
• Все ссылки обязательно заканчиваются завершающим обратным слэшем "/".

Взаимодействие с объектами

• GET параметры только для фильтров и паджинации (постраничного вывода)
• PUT, POST и PATH всегда имеют Content-Type: application/json
• Создание сущности - всегда POST c параметрами в теле.

• Так же, оправка данных, которые при обработке содержат сложную логику, то:

  1. POST - если данные создаются
  2. PUT - если данные обновляются
  3. PUT - если данные создаются или обновляются

• Обновление сущности - всегда PUT
• Удаление сущности - всегда DELETE

Примечание: Метод PATH не используется из за затрудненной поддержки на клиентской стороне

Формат ответа

Ответ всегда в формате json и содержит определенные поля:

• code - HTTP код ответа

• status - Статус ответа, может быть succes, error и fail.

  • succes - успешный ответ, коды статусов в диапазоне {1,2,3}xx
  • error - отрицательный ответ, коды статусов в диапазоне 4xx
  • fail - ошибка сервера, коды статусов в диапазоне 5xx

• message - сообщение о ошибке, покахывается при статусе error и fail
• data - тело ответа

Пример:

{"code":200,"status":"success",
            "data": {"lacksTOS":false,
                    "invalidCredentials":false,"authToken":
                    "4ee683baa2a3332c3c86026d"}
                    }

{'status': 'error', 'message': 'Not found device. Before call register it',
    'code': 403, 'data': 'Not found device. Before call register it'}

Постраничный вывод

Некоторые списки сущностей могут быть слишком большими, и используется постраничный вывод, например:

{ "status": "success",
  "code": 200,
  "data": {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "id": 1,
        "url": "http://ya.ru/",
        "name": "Литовский металл",
        "category": {
          "id": 1,
          "name": "Лакшари"
        },
        "logo": "shop_logo/8d/32/8d32576997774fc0b845cb1870fc7a8b-123x55.jpg",
        "rating": 1,
        "fav": true,
        "info": "ИНН к123343455\r\nКОПП цуко\r\nОГРН 1117847027430 "
      }
    ]
  }
}

Где next и previous - это гиперссылки на следующий и предыдущий срез.