Рекомендации и рекомендации по разработке API

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

ОТВЕТЫ

Ответ 1

Я нашел следующее, чтобы стоить смотреть Джошуа Блох - Как создать хороший API и почему это имеет значение

Примеры на Java, но все же вы можете рисовать параллели. Поскольку вы не упомянули о конкретной технологии; Я предполагаю, что вам не нужны нишевые решения.

Ответ 2

Как кто-то, кто должен потреблять тонны API...

Пожалуйста, напишите свой API последовательно:

  • Согласованное присвоение имен в самом API. Используйте глаголы, существительные, ключевые слова ТОЧНО в том же стиле.

  • В соответствии с целевой средой он будет использоваться. Если .NET, ознакомьтесь с рекомендациями по именованию Microsoft.

  • Согласованные концепции. Factory шаблон? Шаблон Builder? Статические методы? Интерфейсы? Просто выберите один и придерживайтесь его. ДЕЙСТВИТЕЛЬНО. Нет такого понятия, как небольшое исключение из правила. Он будет торчать как большой больной палец. Более одного исключения? Ваш API все больше и больше любитель.

Вот еще один: Специфика.

  • Базовые классы, которые я могу реализовать, если вы решите предоставить их, должны иметь мало и четко определенные функции для реализации. Не говорите мне, что "GetData()" возвращает "object []", а затем ожидаю, что я его реализую, выясните, почему мне нужно передать его в строку [], а затем отладить, почему он вызывается 20 раз. Гораздо лучше иметь DataPoint [] GetChartData(), string [] GetLabelData() и т.д. И позволить мне выбрать, какие из них я должен реализовать.

  • Не забудьте глупо с именами: PostRenderColorWheelModifyHSVBaseHandler. Вы часто можете реорганизовать сверхспецифичные вещи на более общие имена + параметры.

  • Строковые параметры - нет-нет! Используйте перечисления. Я не хочу использовать обработчик, например

    PostRenderHandler ( "ColorWheel", "HSV", someDelegate);

Мне бы очень хотелось перечислить, что я могу исследовать:

PostRenderHandler(ModuleType.ColorWheel, Options.ColorWheelHSV, someDelegate);

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

Ответ 4

Это ссылка от Microsoft: http://msdn.microsoft.com/en-us/library/ms229042.aspx

Существует также эта книга: Руководство по разработке рамок: соглашения, идиомы и шаблоны для многоразовых библиотек .NET.

Ответ 5

Я думаю, ваш вопрос не получит ответа на это количество пространства с объемом информации, которую вы даете. Я поместил несколько ссылок, набрав "api design" в google, и на первой странице получилось, что они выглядят довольно хорошо

http://web.archive.org/web/20151229055009/http://lcsd05.cs.tamu.edu/slides/keynote.pdf

http://www.artima.com/weblogs/viewpost.jsp?thread=142428

http://web.archive.org/web/20090520234149/http://chaos.troll.no/~shausman/api-design/api-design.pdf