Интро
Это краткий перевод основных тезисов из брошюры «Web API Design. Crafting Interfaces that Developers Love» Брайана Маллоя из компании Apigee Labs. Apigee занимается разработкой различных API-сервисов и консталтингом. Кстати, среди клиентов этой компании засветились такие гиганты, как Best Buy, Cisco, Dell и Ebay.
В тексте попадаются комментарии переводчика, они выделены курсивом.
Собираем API-интерфейсы, которые понравятся другим разработчикам
Понятные URL для вызовов API
Первый принцип хорошего REST-дизайна — делать вещи понятно и просто. Начинать стоит с основных URL адресов для ваших вызовов API.
Ваши адреса вызовов должны быть понятными даже без документации. Для этого возьмите себе за правило описывать любую сущность с помощью коротких и ясных базовых URL адресов, содержащих максимум 2 параметра. Вот отличный пример:
/dogs для работы со списком собак
/dogs/12345 для работы с отдельной собакой
Я далеко не профессиональный фотограф, но снимать люблю, и периодически мой архив из нескольких десятков тысяч фотографий самого разного качества пополняется фотками с зеркалки, «мыльницы» и трех телефонов, а также видеозаписями с телефонов и видеокамеры. Какой я только софт не перепробовал для поддержания архива фото и видео в порядке! Adobe Lightroom, Apple iPhoto, Google Picasa… 
От переводчика:
