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