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

Question

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

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

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

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

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

Answer 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/

Answer 2

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

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

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

Answer 3

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

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

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

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

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

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

Answer 4

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

Кредит выдан

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