Оригинал статьи

Не смотря на формальное определение, вокруг многих API ведутся бесконечные споры, полноценный это REST, или нет. На самом деле неважно, является ли API полноценным REST, но оно должно иметь некоторые важные свойства:

• Никакого SOAP. Конечно возможны ситуации, когда SOAP API оправдано, например сложность перевода уже существующего SOAP API на REST интерфейс, но нужно понимать, что для SOAP очень тяжело написать клиентскую библиотеку с нуля или сделать еще что-нибудь нестандартное.
• Используйте HTTP глаголы. Использование GET, POST, PUT, и DELETE запросов для CRUD операций сильно облегчает понимание того, что должен делать конкретный запрос. Очень неудобно пользоваться API, в котором изменение данных производится GET запросом.
• Осмысленные имена ресурсов. Использование таких имен (например /posts/23 вместо /api?type=posts&id=23) повышает понятность того, что делает конкретный запрос. Использование параметров URL очень удобно для фильтрации, но у API получается только одна точка входа и целая куча параметров. Модель, использующая такое API, очень быстро становится слишком сложной.
• XML и JSON. Мне нравится JSON. Кто-то предпочитает XML. Лучше всего предлагать оба варианта, если стоимость такого решения не слишком велика. В идеале должна быть возможность переключения между этими форматами простым переключением расширения между .xml и .json.
• Используйте абстракции. Интерфейс API не должен повторять внутреннюю архитектуру вашей системы. Например, в Adwords API существует 25 разных сервисов, каждый из которых видимо соответствует модулю внутренней архитектуры. Пользоваться таким API очень неудобно – если вы хотите получить стоимость клика для каждого вашего объявления, вам придется сделать несколько десятков запросов. С другой стороны Google Analytics data export API позволяет вам предопределять отчеты, так что получение данных по каждому из них требует только одного запроса. Если есть какое-либо действие, которое пользователи будут производить достаточно часто, нужно позаботиться о том, чтобы оно не было усложнено.