В моей компании мы начинаем переходить на веб-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 - но если это дубликат, пожалуйста, дайте мне знать. Кроме того, если это должна быть вики сообщества (я думаю, что люди должны получить кредит за ответы, поэтому я не сделал это один), пожалуйста, дайте мне знать, и я изменю это на.