Тут пришлось посмотреть несколько открытых API стандартов(Cisco, Microsoft, Atlassian, Heroku, Google и др). У всех у них много общего, но есть и интересные особенности. Дальше озвучу несколько инсайтов:
1. Все, за редким исключением юзают ETag'и для кеширования. ETag — отличный инструмент, который, впрочем, всегда казался мне немного маргинальным. Однако же, оказывается, это не так и все его активно используют
2. У Adidas отличное API. Не, серьезно, почитайте! Тут вам и HATEOAS и HAL и еще куча всего полезного
3. Почти у всех есть поддержка long-running operations, а вот batching многие обходят стороной. Мне это кажется странным, т.к. поддержка батчевых операций всегда казалась мне признаком зрелого API
4. У всех, конечно же, присутствует базовая гигиена а-ля стандартные форматы ошибок, пейджинг, фильтрация и т.д. Кто-то придумывает свои велосипеды типа Facebook projections, кто-то даже пытается это стандартизировать(привет OData). А что если я скажу, что есть RFC на API-ошибки и на кросс-ресурсные ссылки? Лично для меня это стало большим открытием
5. Мне очень понравилась идея использования content negotiation для версионирования API. Идея простая: клиент передает версию апи в заголовке Content-Type (например
Content-Type: application/vnd.example.resource+json; version=2.1.3) и API обязано отдать ответ версии не ниже указанной или 4066. Если для Вас отключение устаревшего API является большой проблемой, то замечательный Sunset Header может немного подсластить пилюлю
7. Если у вас часто тянут толстые ресурсы, то советую подсмотреть концепцию Delta queries. Это позволит ценой небольшого оверхеда отдавать только ту часть информации, которая изменилась с последнего запроса
8. Ну и закончу, пожалуй, мегахоливарным твитом Филдинга про версионирование. Похоже батя REST'а категорически против версий в url, что не мешает подавляющему большинству API версионироваться именно через url
Если Вы знаете\хотите поделиться своим крутым стандартом API(не важно REST\SOAP\(g)RPC\else) кидайте в комменты, Родина вас не забудет)
