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

Чтобы не писать кучу текста,достаточно привести несколько примером хорошо известных компаний, и постараться действовать также.

Примеры:

Facebook
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.