Стабильность
Если вы предлагаете API для своего веб-приложения, это, вероятно, связано с тем, что вы хотите, чтобы другие люди создавали приложения, используя его. Если он нестабилен, они будут ненавидеть вас за то, что вы заставляете их выполнять ваши частые изменения . Если это займет слишком много времени, их сайт может оставаться нефункциональным в течение длительного времени, пока они ищут новый способ работы с вашим API.
Компактность
Вы хотите, чтобы API был полным, но компактным , т.е. не слишком много для запоминания.
Ортогональность
Сделайте так, чтобы был один и только один способ изменить каждое свойство или инициировать действие. Действия в ортогональном API должны иметь минимальные (если вообще) побочные эффекты .
Кроме того, не рекомендуется удалять функцию из общедоступного API после выпуска.
Безопасность и аутентификация
Поскольку API доступен в Интернете, вам нужно будет аутентифицировать каждый запрос и предоставить соответствующий доступ. Здесь применяется здравый смысл в области безопасности.
Быстрые ответы или разбиение на части
Я считаю, что в веб-среде мы должны получать быстрые ответы и избегать запросов, выполнение которых займет слишком много времени. Если это неизбежно, то лучше отправить ACK и разбить задачу на несколько частей и последующие вызовы.
Из моего По опыту, все хорошие API созданы не для решения общей проблемы, а для решения некоторых проблем, требующих определенной абстракции. Эта абстракция затем развивается по мере изменения требований и / или нижележащего уровня.
Поэтому вместо того, чтобы найти API , который сделает все это, я бы начал с поиска одной или двух хороших примеров проблем, когда ваш API мог бы помочь.