Именование ресурсов
Кроме правильного использования HTTP методов, именование ресурсов, вероятно, самая обсуждаемая и важная концепция для понимания во время создания понятного и легко используемого API для Web-сервиса. Когда ресурсы названы хорошо, API интуитивен и лёгок в использовании. Если же ресурсы названы плохо, тот же самый API может показаться неуклюжим и трудным в понимании и использовании. Ниже приведены несколько подсказок, как продолжить создавать URI ресурсов для нового API.
Фактически RESTful API - это всего лишь набор URI, HTTP вызовов к этим URI и некоторое количество представлений ресурсов в формате JSON и/или XML, многие из которых будут содержать перекрестные ссылки. За основу адресации берется покрытие уникальными идентификаторами ресурсов (URI) У каждого ресурса есть свой адрес или URI: вся интересная информация, которую сервер может предоставить, представлена как ресурс. Ограничение однообразия интерфейса частично реализовано с помощью комбинаций URI и HTTP методов и их использованием в соответствии со стандартами и конвенциями.
Каждый ресурс сервиса должен иметь хотя бы один URI, идентифицирующий его. И лучше всего, когда этот URI имеет смысл и адекватно описывает этот ресурс. URI должны иметь предсказуемую, иерархическую структуру, чтобы увеличить понятность и, как следствие, юзабилити: предсказуемость означает, что они консистентны, иерархичность означает, что у данных есть структура взаимоотношений. Это не принцип и не ограничение REST, но это улучшает API.
RESTful API пишут для потребителей. Названия и структура URI должна передавать смысл этим потребителям. Очень часто трудно понять, где должны быть границы, но с пониманием ваших данных вы поймете и то, что имеет смысл возвращать как представление вашим клиентам. Проектируйте для клиентов, а не для ваших данных.
Давайте предположим, что мы описываем систему с покупателями, заказами, отдельными позициями, продуктами и т. д. Рассмотрим URI, включенные в описание ресурсов этого сервиса:
Хорошие практики
Чтобы создать нового покупателя в системе мы используем:
POST http://www.example.com/customers
Чтобы получить информацию о покупателе с ID# 33245:
GET http://www.example.com/customers/33245 Тот же URI мы используем для PUT и DELETE, чтобы обновлять и удалять, соответственно.
Ниже предложены URI для продуктов:
POST http://www.example.com/products для создания нового продукта.
GET|PUT|DELETE http://www.example.com/products/66432 для чтения, обновления, удаления продукта с ID# 66432, соответственно.
Плохие практики
Например, чтобы обновить данные покупателя с ID 12345 и получить их в формате JSON может быть использован такой запрос:
GET http://api.example.com/services?op=update_customer&id=12345&format=json
Несмотря на то, что узел URL-адреса 'services' — существительное, он не является самодокументируемым, поскольку иерархия URI не одна и та же для всех запросов. Кроме того, он использует метод GET, хотя выполняет обновление. Это контринтуитивно, опасно и вызывает много боли у клиентов.
Взгляните на эти два тренажёра API, чтобы получить начальное представление об API: