Примеры лучших веб-интерфейсов SOAP/REST/RPC? И почему они вам нравятся? И что с ними не так?

В моей компании мы начинаем входить в веб-API для доступа и обновления наших данных; первоначально для партнеров, но затем, вероятно, для общественности в будущем. На данный момент API API (например, SOAP, REST, RPC) полностью открыт, и мы пока не принимаем никаких решений, поэтому меня интересуют оба примера веб-API, которые люди считают хорошими, и почему вы думаете что.

Мне интересны мнения людей, использующих разные языки (мы, вероятно, будем предлагать API людям, использующим несколько платформ, в частности,.NET, Java, ActionScript и JavaScript) о веб-API, которые вы думаю, хорошие примеры, и что у вас были хорошие впечатления.

Некоторые моменты, которые я хотел бы затронуть:

Вы предпочитаете услуги типа SOAP или REST/RPC? Я подозреваю, что люди с поддержкой платформы (например,.NET, Java) предпочтут SOAP, и люди, использующие языки без поддержки платформы, предпочтут другие, но я хотел бы подтвердить это предположение.
Вам не нравится, действительно ли API является RESTful, или это простой старый RPC-стиль HTTP GET/POST? Если да, то почему вас это волнует? Является ли более важным, чтобы API правильно описывал (т.е. Не утверждал, что он RESTful, если он является RPC-стилем), чем тот, который на самом деле является одним из двух?
Нам нужно проверить, кто пользуется службой. Я просматриваю аутентификацию Amazon S3, которая использует открытый идентификатор и частный токен, который используется для хэш-параметров запроса в токен проверки (это также похоже на flickr). Вы использовали этот тип аутентификации раньше, и как вы с ним справились? Существуют ли какие-либо алгоритмы хеширования, которые вы находите проблематичными (т.е. Не поддерживаются вашей платформой)? Вы предпочитаете отправлять хеш в HTTP-заголовке или в URI?
Как управлять версиями? Это хорошая идея иметь подкаталог типа /v1/, чтобы будущие версии можно было добавлять рядом или вы делали бы что-то по-другому, как версия в полезной нагрузке или запросе запроса? Как долго вы ожидаете, что версия API, которую вы построили против, будет поддерживаться (например, если v2 был введен в действие, какова будет ваша ожидаемая продолжительность жизни v1).

Кроме того, любые другие мнения и точки, которые будут рассмотрены, будут полезны.

Я намеренно не смущаюсь по фактическому типу API, который мы реализуем, поскольку я ищу общее руководство с точки зрения того, что люди считают хорошими API-интерфейсами и механизмами реализации, поэтому этот пост и его ответы будут полезны для большего количества людей в будущем.

Примечание. Я искал и не могу найти общий вопрос об этом - все они кажутся специфичными для определенного типа API, но если это дубликат, то, пожалуйста, дайте мне знать. Также, если это должна быть вики сообщества (я думаю, что люди должны получить кредит на ответы, поэтому я не сделал ее одной), тогда, пожалуйста, дайте мне знать, и я изменю ее.

Ответ 1

Вот мой прием.

Хотя с точки зрения Java я предпочитаю REST. Конверт SOAP с несколькими пространствами имен и его сложной структурой - мерзость. Он пытается решить в основном мнимые проблемы и не решает ничего эффективно. Единственное что касается SOAP, который я нашел полезным, это то, что он имеет стандарты авторизации и ошибок. С другой стороны, их можно было бы решить гораздо проще, включив четыре стандартных атрибута в корневой элемент XML - имя пользователя, пароль, errorCode, errorDescription.
Хорошее описание API и документация действительно важны. Разница между REST и SOAP в зрелой структуре в основном состоит из нескольких строк конфигурации.
Для SOAP отправьте хэш как часть безопасности SOAP; для REST мне нравится упаковывать все в полезную нагрузку и избегать HTTP-заголовков для аутентификации. У меня есть только субъективные причины, так как мне пришлось сражаться с фреймворками, которые нелегко выставляют HTTP-заголовки.
Мои личные предпочтения имеют разные URI для разных версий протокола. По моему опыту, это дает вам больше гибкости в новых версиях, а старые клиенты, которые подключаются к неподдерживаемым версиям протокола, перестают работать сразу и по понятным причинам. Кроме того, иногда вы можете сопоставить старую версию приложения с старым URI, чтобы избежать использования устаревшего кода поддержки в новой версии сервера.

Как долго вы поддерживаете старую версию протокола... в идеале, как долго поскольку у вас есть клиенты, которые его используют. Это больше, чем техническое решение. Вы должны поддерживать хотя бы одну предыдущую версию протокола. Обычно в ваших интересах подталкивать клиентов к новой версии для снижения стоимости поддержки устаревших; со стороны клиентов новая версия должна означать новые функции, лучший протокол и какой-то дополнительный стимул для бизнеса (если только новых функций недостаточно).

Ответ 2

Вам может быть интересна презентация Джошуа Блоха "Как создать хороший API и почему это имеет значение". Джошуа Блох является автором "Эффективной Java" и главным инженером программного обеспечения и главным архитектором Java в Google.

Аннотация: http://portal.acm.org/citation.cfm?id=1176622

Слайды: http://lcsd05.cs.tamu.edu/slides/keynote.pdf

Видео: http://www.youtube.com/watch?v=aAb7hSCtvGw

Ответ 3

Версии для REST с использованием заголовков Content-Type хорошо описаны здесь: http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

Ответ 4

Подход RPC также является хорошим вариантом. Это уменьшает накладные расходы, и такие проекты, как Ice, Google Protocol Buffers и Apache Thrift, упрощают разработку служб на основе RPC.

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

Ответ 5

Я бы посмотрел, что делает Amazon - http://aws.amazon.com/ - ребята, зарабатывающие деньги на этом материале, очевидно, извлекут больше уроков, чем кто-либо еще.

Другой API, на который я бы посмотрел - salesforce.com и Microsoft CRM api были довольно интересными. У Twitter есть битва, усиленная REST api тоже.

Ответ 6

ИМХО, все зависит от того, какие приложения вы предлагаете. Если вы делаете важные транзакции с большим временем, то обязательно отправляйтесь с SOAP ( "Смертельная звезда WS", как они ее называют). Но если вы предлагаете социальные приложения, перейдите в REST, так как это проще и лучше подходит для публичного взлома.

Ответ 7

REST, если все сделано правильно, легко понять (модели HTTP), прост (ориентирован на ресурсы) и может быть проанализирован практически на любом языке программирования (XML).

Ответ 8

Если вы не можете решить, в конце концов, вы сможете реализовать их все. В этих случаях полезно посмотреть, как это сделали другие. Я рекомендую вам базовую базу данных с открытым исходным кодом eXist, что предлагает три типа интерфейсов, которые вы задумываетесь.