No Image

Создание api для сайта

СОДЕРЖАНИЕ
1 просмотров
10 марта 2020
  • Переводы, 23 декабря 2014 в 12:54
  • Антон Машков

Хороший API — это немаловажная часть успеха. Бывает, что это единственная причина, почему выбрана именно эта библиотека или этот продукт. Создать хороший API не так-то просто, и не существует однозначного пути для его создания, потому что для каждого отдельного случая нужен свой подход. Те, кому нередко приходилось использовать различные библиотеки, наверняка уже неплохо представляют, что именно представляет собой хороший API. Постараемся собрать все точки зрения воедино.

1. Универсальный, но удобный

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

  • Вам нужен пустой конструктор, который создает пустой объект, поля которого будут заполнены позже;
  • Необходимы set/get методы для работы с именем и фамилией;
  • И методы для обработки дополнительных полей имени/фамилии (у некоторых людей бывает больше двух слов в имени).

Из описания всех этих методов можно составить полный API. А для удобства давайте отдельно выделим документацию по таким элементам:

  • Конструктор с двумя параметрами: именем и фамилией, т.к. такая комбинация наиболее часто встречающаяся в мире;
  • Set/get методы для дополнительных имен, т.к. в некоторых культурах мира большая часть людей имеет более одного имени. Если же приложение создается специально для таких стран, то в конструктор из первого пункта имеет смысл добавить еще параметры.

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

2. Применимый в любом случае, но не слишком большой

Этот пункт, пожалуй, можно было бы объединить с первым, но хотелось бы все же уделить ему больше внимания.
Большая часть документации строится по принципу «А что, если…» Хотя здесь, пожалуй, необходимо себя ограничивать, потому что нет определенных границ для рассмотрения всех возможных случаев. Точно не скажешь, от чего именно стоит избавиться, ибо все зависит от конкретной ситуации. Между тем, вот несколько советов:

  • То, на чем многое завязано, что не менялось в течение долгого времени, следует обновлять постепенно, желательно, предупреждая об этом заранее.

Например, IPv6. Мы так долго пересаживаемся на новый протокол, т.к. большое количество программного обеспечения строго привязано к IPv4. Правильно ли это? Пожалуй, да. Сейчас у программиста имеется выбор, использовать ли современную технологию или же даже реализовать одновременную поддержку различных протоколов. Стоит ли это потраченного времени? Решать вам.

  • Удобство классов и методов сохраняется до тех пор, пока понятно, что эти классы или методы из себя представляют и за что отвечают.

3. Названия методов должны быть осмысленными, доступными для понимания, структурированные и по возможности короткие

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

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

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

И наконец, не стоит придумывать слишком длинные имена. Конечно, чем длиннее, тем, обычно, яснее смысл, но все же всегда существует некоторая граница, переход через которую приведет к тавтологии. Например, Integer_Maximum_Value бесполезно длиннее, чем INT_MAX, а обладает той же смысловой нагрузкой.

Читайте также:  Развертывание windows 10 по сети

4. Ориентирован на повышение производительности, но без потери удобства

К некоторым API не приходится обращаться часто, другие же должны всегда быть под рукой, а потому не пользование ими не должно снижать производительности программиста. И при этом никогда нельзя забывать об удобстве. Например, API Windows – пример того, как удобством пожертвовали в пользу производительности. Ему не хватает функций, заполняющих структуры данных значениями по умолчанию. Раздражает обнулять каждый элемент отдельно. С другой стороны, некоторые функции можно было бы назвать лишними: иногда несколько функций очевидно стоило бы заменить на одну. К примеру, FindFirstFile() и FindNextFile() можно было бы объединить, а вот ZeroMemory() стоило бы заменить на более эффективную memset().

5. Удобные константы

Чем реже разработчику приходится сужать область применения методов, классов и т.п. для лучшего их понимания, тем лучше. В большинстве случаев…
Константы должны также иметь логичные названия.
C другой стороны, неплохо также позволить задавать константы специфичной области применения.

6. Правильно выбирайте формат файла для представления вашего API

Коротко говоря – не останавливайтесь слепо на XML.
Если вы работаете над веб-сервисом, то задумайтесь, в каком виде представить документацию: это может быть XML, JSON или что-то еще. Подумайте о тех, кто будет пользоваться вашим API. Заставлять людей использовать XML это… ну, ладно, используйте XML, если ничто другое вас не устраивает.

7. Настраиваемый, но в меру

Здесь речь идет о фреймворках. Многие из них позволяют пользователю изменять поведение некоторых элементов за счет изменения параметров конфигурации. Это хорошо, но надо знать меру. Во-первых, необходимо понимать, что какие-то конфигурации совершенно бестолковы. Чем больше параметров поддается изменению, тем сложнее учесть все возможные конфигурации, не говоря уже о том, что какие-то значения параметров могут оказаться несовместимы и неблаготворно скажутся на работоспособности.
«Абсолютно все можно подключить, расширить и настроить» – не самый верный подход. Лучше не иметь возможности настроить, чем настраивать так, чтобы ничего не работало.
В особенных случаях можно ограничить возможности конфигурирования «белым ящиком»: вместо увеличения количества комбинаций параметров по принципу «черного ящика», можно разбить все настройки на группы заранее выставленных значений, и пользователь будет подстраивать фреймворк под себя, комбинируя эти наборы настроек.

8. Одновременное выполнение vs. Однопоточность

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

9. Не все знают английский язык

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

10. Совместимость со старыми и новыми версиями

В идеале, любая новая версия должна быть совместима со всеми предыдущими. Но на практике это, пожалуй, невозможно. Вот несколько советов:

  • Изначально разрабатывайте API так, чтобы его можно было расширить в будущем. Особенно будьте осторожны с аргументами логического типа (их можно заменить нумерованным типом);
  • Если о каких-то фичах, которые будут введены в будущем, вам известно заранее, то вы можете сразу же включить их в API для обеспечения совместимости с будущими версиями;
  • Внимательно следите за сохранением совместимости с предыдущими версиями, но не реализовывайте рефлексию своего API, потому что в будущем вам придется учитывать и совместимость с механизмом самообработки API;
  • Лучше делайте большие перерывы между выпусками новых версий API, чем выпускайте частые обновления. Конечно, никто не любит подобных перерывов, но вот необходимость часто обновляться, кажется, особенно раздражает разработчиков;
  • Не пренебрегайте альфа/бета-тестированиями, потому что лучший путь развития – это развитие в соответствии с откликами пользователей.
Читайте также:  Мтс пишет вызов завершен

11. Излишнее удобство не оправдано

Нельзя не придавать достаточного значения времени разработчика. Если программист пишет меньше кода, это не значит, что он мало работает.
Когда вещи работают авто-магически, их бывает трудно изменить в соответствии с выполняемой задачей.

Заключение

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

В этой статье я хочу рассказать о том, как можно написать api для своего сервиса. Сделаем сервис по проверки корректности e-mail адреса. То есть, мы будем вызывать нашу api функцию, передавать ей параметр, в данном случае e-mail, а в ответ api должно вернуть результат проверки или код ошибки.

Для начала нужно определиться, что и как будет отвечать api. Я думаю, самый простой способ сделать ответ в формате JSON. А возвращать будем ассоциативный массив, состоящий из трех массивов: status, response и error. Status может иметь только два значения, OK и ERROR – это будет обозначать, как прошло обращение к api. Error – тут мы будем передавать числовой код ошибки, если ошибки нет, то передавать будем 0. Response – этот массив будет хранить интересующий ответ: true – если, e-mail адрес корректный или false, если e-mail не корректный.
В теории, надеюсь все ясно, теперь непосредственно код. Создадим скрипт api.php:

Все, наше api готова, теперь попробуем сделать вызов нашей api функции, для этого создадим скрипт api_test.php

В скрипте мы пробовали вызывать api в php скрипте, но также можно сделать вызов с помощью java script

Как написать свое API: 3 комментария

Я вставляю этот код у себя на сайте. Он не работает почему — то. Ничего не изменял

В html форме нужно указать
То есть для работы этого кода нужно бы сделать форму ввода мыла.
Все работает.

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

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

  • Социальные сети (Facebook и другие). Здесь требуется API для получения информации о различных данных пользователя: его друзьях, личных сообщениях и прочей информации.
  • Почтовые сервисы (например, mail.ru). В первую очередь, для получения писем. Иногда для отправки.
  • Различные сервисы для создания Интернет-магазинов. Например, получить список новых заказов или список всех товаров в заданной категории.
  • И много-много других сайтов.

Первое, что необходимо усвоить — это то, что API нужен далеко не каждому сайту (даже если он принадлежит одной из вышеуказанных групп).

Если же Вы считаете, что API на Вашем сайте необходим, то давайте разберём пример того, как он создаётся. Пусть у нас будет такая задача: есть ЭПС (как, например, WebMoney). И мы хотим, чтобы пользователь мог из своего кода, пользуясь нашим API, узнать свой баланс на счёте.

Создадим файл (например, api.php), который у нас будет принимать GET-запросы от пользователей на получение различной информации. Напишем в этом обработчике такой код:

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

Этот запрос пользователи формируют в своих скриптах (например, через cURL). Параметр key — это уникальный ключ каждого пользователя. И ответом этого запроса будет число, отвечающее за баланс пользователя. Аналогично создаются и все другие возможности API. Можно добавлять другие различные параметры: например, получить список операций пополнения счёта с одной даты по другую. Желательно, сами списки возвращать в формате JSON.

Читайте также:  Функция гпр в excel для чайников

Вот так легко и просто создаётся API для сайта. Безусловно, нужен он Вам или нет — решать только Вам, а всю самую необходимую информацию я Вам только что дал.

Копирование материалов разрешается только с указанием автора (Михаил Русаков) и индексируемой прямой ссылкой на сайт (http://myrusakov.ru)!

Добавляйтесь ко мне в друзья ВКонтакте: http://vk.com/myrusakov.
Если Вы хотите дать оценку мне и моей работе, то напишите её в моей группе: http://vk.com/rusakovmy.

Если Вы не хотите пропустить новые материалы на сайте,
то Вы можете подписаться на обновления: Подписаться на обновления

Если у Вас остались какие-либо вопросы, либо у Вас есть желание высказаться по поводу этой статьи, то Вы можете оставить свой комментарий внизу страницы.

Порекомендуйте эту статью друзьям:

Если Вам понравился сайт, то разместите ссылку на него (у себя на сайте, на форуме, в контакте):

Она выглядит вот так:

  • BB-код ссылки для форумов (например, можете поставить её в подписи):
  • Комментарии ( 20 ):

    что такое API — ссылка не та)

    Большое спасибо! Уже исправлено.

    и что такое формат JSON?

    Об этом будет моя следующая статья, которая выйдет в понедельник. Но если быть совсем кратким, то это аналог ассоциативного массива в PHP.

    А можно ли написать для ИГР АПИ?! Как вк например, что бы определяло кто заходил,его действия, что бы можно бло играть друг с другом?!

    Для онлайн-игр, конечно, можно.

    А вы можете мне помочь?!

    Составьте техническое задание, отправьте мне на e-mail: myrusakov@gmail.com. Если будет возможность и время, я соглашусь выполнить.

    по моему ето полный фигня получить список друзей в соц сеть через api

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

    но для использования api ради список друзей ето действительно беcмислено , для получения id друзей хватит 3-4 строк кода

    Где 3-4 строки кода? На стороне пользователя должна быть 1 строка кода с запросом. А на стороне сервера сам API никак не может быть на 3-4 строки. И API содержит не только список друзей, но ещё кучу функций. Список друзей лишь пример.

    я имел введу только друзья а вообще я постараюсь использовать post запросы а не get так боле безопасно а апи в основном надо для рассылок, или поделится своим скриптом с другими сайтами

    У вас тавтология в этом предложении "Желательно, сами списки возвращать желательно в формате JSON."

    До речі, планую для апі зробити щоб можна було відправляти REST-правильні http запити(PUT, DELETE..). Є якійсь правильні способи дістати глобальні масиви з ними крім танцями з бубном навколо php://input?

    в принципе,нету Только так) Либо при помощи стандартных глобальных переменных Так Вы создайте класс определённый и подключайте его,где нужно

    где key=fa9sgwlgjs9gdsjlgjdsjglsdlgs key — это поле в базе? fa9sgwlgjs9gdsjlgjdsjglsdlgs — значение key? Я заменил getbalance на своё получилось вот: select_db(‘nameDB’) or die(‘Cannot select database’); if ($_GET[‘method’] == "get.newsDate") < $date; echo $date; >?> ничего не выводит

    API на сайте -сложнось в посыле http:// В адресной строке или в форме нухно отправлять?В адресной строке пустая страница всегда.Со временем может дойдет.Но пона ето никчему,но полезно это знать.

    Здравствуйте. У меня имеется на сайте API, но в нём не хватает некоторых методов. Возможна ли доработка, имеющегося API? Если да, то можно ли с Вами обговорить этот вопрос, или может дали бы контакты того кто этим занимается. Вообще, нужна доработка методов для создания нативного приложения для сайта. Заранее спасибо.

    Для добавления комментариев надо войти в систему.
    Если Вы ещё не зарегистрированы на сайте, то сначала зарегистрируйтесь.

    Copyright © 2010-2019 Русаков Михаил Юрьевич. Все права защищены.

    Комментировать
    1 просмотров
    Комментариев нет, будьте первым кто его оставит

    Это интересно
    Adblock detector