REST-дизайна – это делать вещи просто и понятно.
Описание любых сущностей через коротки и ясные URL адреса,которые могут должны содержать максимум 2 параметра.
/cars – список автомобилей
/cars/987 -конкретный автомобиль
Использовать в названиях базовых URL-ов существительные вместо глаголов.
Так не надо:/newCar,/saveCar,/delCar
Единственное где возможно использование глаголов, єто если выполнение каких-то действий, не связанных с абстракцией.
К примеру /convert?from=EUR&to=USD&amount=100
Мы выполняем процедуру конвертации.
Принцип CRUD — Create — Read — Update — Delete
POST /cars — создать новую машину
GET /cars — загрузить список машин
PUT /cars — редактиврование всех машин сразу
DELETE /cars — удалить все машины
POST /cars/987 — вернуть ошибку (машина 987 уже создана)
GET /cars/987 — показать информацию о машине
PUT /cars/987 — редактировать машину 987
DELETE /cars/987 — удалить машину 987
Множественные и единичные числа.
1.Использовать описание существительных в базовых URL-ах лучше в множественном числе, хуже в единственном.
Нельзя смешивать два типа существительных(множественное и единственно).
Использование реальных и абстрактных имен в базовых URL-ах
целесообразно использовать реальные имена,вместо абстрактных.
Например:
/cars,/bikes,/smiles,/boats вместо /items,/list
Связи в ресурсах
/ресурс/идентификатор/ресурс
Какой формат ошибок корректный для API
Чтобы не писать кучу текста,достаточно привести несколько примером хорошо известных компаний, и постараться действовать также.
Примеры:
HTTP Status Code: 200
{“type” : “OauthException”, “message”:”(#803) Some of the aliases you requested do not exist: foo.bar”}
Twilio
HTTP Status Code: 401
{“status” : “401”, “message”:”Authenticate”,”code”: 20003, “more info”: “http://www.twilio.com/docs/errors/20003”}
SimpleGeo
HTTP Status Code: 401
{“code” : 401, “message”: “Authentication Required”}
Коды ошибок HTTP для API
Возможно только 3 варианта ответов API
Запрос прошел успешно
На вход были переданы неправильные данные — клиентская ошибка
Произошла ошибка при обработке данных — серверная ошибка
Так что можно взять за основу 3 кода ответов:
200 OK
400 Bad Request (некорректный запрос)
500 Internal server error (внутренняя ошибка сервера)
Если 3-х кодов вам недостаточно — возьмите еще 5:
201 Created (Запись создана)
304 Not Modified (Данные не изменились)
404 Not Found (Данные не найдены)
401 Unauthorized (Неаторизованный доступ)
403 Forbidden (Доступ запрещен)
Всегда указывайте в API версию
К примеру:
Twilio /2010-04-01/Accounts
salesforce.com /services/data/v20.0/sobjects/Account
Facebook ?v=1.0
Но есть замечания:
Twilio требует при каждом запросе к API передавать время, когда приложение разработчика было скомпилировано. На основе этой даты Twilio определяет, какую версию API нужно предоставить приложению. Это умный и интересный подход, но слишком сложный. А еще можно легко запутаться с датами.
Salesforce.com вставляет v20.0 в середину адреса API запроса. И это очень хороший подход. Но не стоит использовать точку в нумерации версии — это провоцирует излишне частые изменения в интерфейсе API. Можно сколь угодно часто менять логику работы внутри API, но вот сами интерфейсы должны меняться максимально редко. Так что лучше обойтись без точки и не искушать себя.
Facebook тоже использует нумерацию версий в запросе, но прячет её в параметры запроса. И этот подход плох тем, что после очередного внедрения новой версии API все приложения, не передающие версию в запросе, начинают глючить.
Используйте префикс v, целые числа и располагайте номер версии в левой части адреса.
Например:
/v1/dogs
Держите в рабочем виде как минимум одну предыдущую версию
Еще можно указывать версию в заголовках ответа сервера. Это может давать некоторые дополнительные возможности при работе с API. Но если вы используете множество разных версий и требуете обязательно указывать их в заголовках — это симптом большой проблемы.
Пагинаций, или разбиение на страницу
Если данных много, и выводить их нужно постранично.
То эти параметры должы быть включены в запрос к API
Пример:
/cars?limit=25&offset=50
Где:
limit=25 – это лимит который выводит кол-во данных за один запрос.
offset=50 – это смещение,которое показывает с какого указателя отсчитывать лимит.
По умолчанию, лимит может быть =10, а смещение будет равно в любом случае 0.