Рекомендации по написанию API

Я собираюсь написать api и подумал, что найду хорошие рекомендации о том, что нужно искать, как написать хороший api.

Я, конечно, сделал поиск в Google, но, помимо этого, от Dustin Diaz http://www.dustindiaz.com/api-writing-tips/, я действительно не смог найти хорошие рекомендации.

Какие вещи вы хотели бы сделать по-другому при создании API? Что имело наибольшее значение.

Я предполагаю, что буду использовать oauth.

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

Ответ 1

Ключевые моменты, которые я бы рекомендовал вам посмотреть:

Внедрение интерфейса RESTful
Предлагаем различные форматы данных (JSON, XML и т.д.)
Сделать синтаксис понятным и понятным
Тщательная документация
Использовать правильные коды ответов

Кроме того, вот некоторые ссылки, которые могут вам пригодиться:

http://www.slideshare.net/eaton/building-apis-that-rock
http://www.notiondesign.ca/blog/story/how-not-to-build-an-api/
http://blog.apigee.com/category/api_best_practices/
http://blog.isnotworking.com/2007/05/api-design-guidelines.html

Кроме того, это отличная книга, которая может помочь вам начать:

http://www.amazon.com/dp/0596529260/

Ответ 2

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

выполняется ли управление памятью вручную, с помощью RAII или с сборкой мусора.
поддержка общего программирования, объектно-ориентированного программирования, функционального программирования и т.д. на языке.
какая система использует язык.

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

Ответ 3

API
должен быть ясным Легко обучаема Прост в использовании, даже без документации Трудно злоупотреблять Функциональность должна быть легко объяснима Имена должны быть в значительной степени понятными Имена должны быть последовательными: одно и то же слово должно означать одно и то же через весь API API должен быть регулярным, иметь некоторую симметрию

Кредит, предоставленный

http://sharismlab.com/blog/2012/07/21/how-to-write-an-api-for-your-web-app/

Ответ 4

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

API-интерфейс для веб-служб:
Определите, какой протокол, форматы данных и аутентификацию вам нужно использовать.
Большинство веб-служб реализуют API со следующими параметрами.

Protocol: HTTP
Dataformat : JSON/XML
Authentication : API key/Oauth

реализация API для библиотек и SDK:
  Создайте прототипы, которые должны быть заморожены из жизни.
  Разверните API, добавив дополнительные функции и не изменяйте прототипы существующих функций.
  Разрешить пользователям предоставлять как можно больше входов в качестве аргументов для функций.       Таким образом, приложение может выполнять свою работу по запросу пользователя.

Имейте в виду, и API должен позволить пользователю использовать его с минимальными усилиями.

См:
Введение в API: https://zapier.com/learn/apis