Написание интерфейса для API веб-сервиса

Question

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

Должен ли я иметь один URL и передавать всю информацию в качестве параметров запроса:

http://hostname/api/v1?func=getZipCode&state=Ohio&city=Toledo&street='100 Cherry Street'

Или что-то RESTful:

http://hostname/api/v1/getZipCode/Ohio/Toledo/100 Cherry Street

Или мыльный путь:

POST /api/v1 HTTP/1.1

<?xml version="1.0"?>
<soap:Envelope>
<soap:Body xmlns:m="http://hostname/api/v1/wsdl">
  <m:getZipCode>        
    <m:state>Ohio</m:state>
    <m:city>Toledo</m:city>
    <m:street>100 Cherry Street</m:street>
  </m:getZipCode>
</soap:Body>
</soap:Envelope>

Каковы (не) преимущества каждого подхода?

Answer 1

Ваш пример "REST" на самом деле не имеет ничего общего с REST, это просто симпатичный URI. Проверьте другие вопросы о StackOverflow, которые объясняют, что такое REST, или прочитайте диссертацию Филдинга по REST для авторитетного источника.

Одним из преимуществ по сравнению с SOAP и RPC, которое имеет REST, является менее хрупкое API из-за минимизации связи между URI и ресурсами. В REST вы перемещаетесь по ресурсам через гипертекст - каждый ответ на представление ресурса будет содержать URI связанных ресурсов, так что единственный URI, который вам нужен в опубликованном API, - это одна точка входа. В RPC вы обычно включаете все возможные URI в свой API, что является огромной связью и чрезмерно хрупким. Сервер должен иметь возможность управлять своим собственным пространством URI, как в REST.

В SOAP вы просто используете один URI для всего, к чему вы POST. POST-запросы не кэшируются, так что это один огромный недостаток. SOAP не пытается вписаться в стек HTTP, как это делает REST - он просто использует HTTP в качестве туннеля.

Answer 2

Если вы хотите быть RESTful, не помещайте в URI какую-либо служебную версию, например "v1".Некоторые идеи о версии REST Web Services, описанные Питером Уильямсом здесь и здесь .

Answer 3

На каких языках вы пользуетесь клиентами? Какие инструменты они должны использовать ваши услуги? Я бы сосредоточился на выборе того, что хорошо поддерживается в их средах программирования.

У меня был хороший успех как с REST, так и с SOAP с точки зрения потребляемости. Мои Java-реализованные сервисы были потрачены без особых технических усилий со стороны разработчиков .NET.

Подход SOAP является частью всего WesbServices в его облике WS- *: в нем есть вариации и расширения для детальной защиты, асинхронной доставки, транзакций и всех других полезных вещей. Если эти более тяжелые требования могут появиться в будущем, я бы выбрал SOAP.

Если ваши клиенты с большей вероятностью будут клиентами AJAX в браузере, тогда REST с полезной нагрузкой JSON может очень хорошо подойти.

Резюме, сосредоточиться на потребностях и возможностях клиентов. Сделай их жизнь проще.

Answer 4

Прежде чем рассматривать особенности вышеупомянутых альтернатив, я бы оценил существующие стандарты на предприятии. Конечно, если их нет, тогда вы действительно можете выбирать, исходя из своих потребностей и предпочтений.

Но вряд ли вы создадите системный API в вакууме. Таким образом, вероятно, большинство решений уже было принято, чтобы охватить один или несколько подходов, и вам просто нужно просмотреть эти решения, понять, как и почему они были приняты, проанализировать их отношения и зависимости с системой, которую вы строите. После этого ваш выбор должен стать гораздо менее неопределенным, поскольку вы больше не разрабатываете только API - вы сейчас разрабатываете решение, которое является частью системы.

ОБНОВЛЕНИЕ: спросите своих будущих и потенциальных клиентов, что они уже используют. Они не хотят использовать еще один стандарт, и, если существующий соответствует вашим потребностям, следуйте ему.

Answer 5

SOAP:

Плюсы:

• В большинстве языков довольно просто взять WSDL и превратить его в необработанный код. Это также дает вам базовые объекты данных, что также является преимуществом.
• Также относительно легко генерировать WSDL из Java и некоторых других языков

Минусы:

• Боль в заднице - иногда работать.
• Это может быть очень многословно. Вы можете передать больше разметки, чем фактическое содержимое.

Получить URL:

Плюсы:

• Довольно просто написать сервер и сервер на большинстве языков.

Минусы:

• Как вы вернете данные обратно пользователю? Придется ли им анализировать какой-либо формат данных?

RESTful

Плюсы:

• Это "сексуально" в эти дни
• Некоторые библиотеки позволяют легко выводить данные в нескольких форматах

Минусы:

• Может быть боль писать в зависимости от языка.
• Если вы действительно не собираетесь делать его "чистым ОТДЫХОМ", это, вероятно, не стоит усилий (и даже тогда сомнительных)