Как сделать api для сайта

Кросс-доменная API для сайта

В данном уроке мы сделаем собственный кросс-доменный API. Может быть вы уже пробовали делать что-то подобное, и, вероятно, сталкивались с невозможностью нормальной работы функций API со сторонних доменов. В основном не получается сделать нормальный запрос AJAX к удаленному серверу и получить ответ в JavaScript функциях. А причина заключается в настройках безопасности. Мы покажем, как решать подобные проблемы.

sourse

Шаг 1. PHP

Первым делом приготовим наш сервер.

api.php

Следует уделить внимание первой строке, в которой используется установка для заголовка ‘Access-Control-Allow-Origin’. Так разрешается отправка ответа любому серверу (что означает — любому домену). Если вы хотите ограничить область использования определенным доменом, делайте это в данной строке. Затем мы выполняем простые операции в зависимости от полученных параметров $_POST. В нашем примере реализуются простые математические операции. Мы возвращаем результат в формате JSON. Теперь время подготовить библиотеку JavaScript.

Шаг 2. JavaScript

api.js

Это обертка для нашей серверной части. В примере подготовлены 4 функции JavaScript: do_sum, do_sub, do_mul и do_div. Для каждой серверной операции. Обобщая, можно сказать, что нужно для правильного запроса: первое, установить необходимы URL для файла серверной части API (например: http://ваш_сайт/api.php); второе, установить для ‘crossDomain’ значение true; и последнее, установить тип данных dataType (для нашего примера ‘json’). Обратите внимание, что третий параметр каждой нашей функции — ‘cfunction’. Это пользовательская функция и нам следует передавать полученный ответ сервера в данную функцию.

Шаг 3. Использование

Небольшой пример использования подобного API.

Здесь показано, как можно использовать функции API. Вот единичный пример:

Мы просто передаем 3 параметра в нашу функцию: 2 цифры и одну функцию. Ответ сервера будет получать данная функция. И можно будет выводить результат где-нибудь (как пример используется элемент #results).

Данный урок подготовлен для вас командой сайта ruseller.com
Источник урока: www.script-tutorials.com/javascript-cross-domain-api-for-your-website/
Перевел: Сергей Фастунов
Урок создан: 23 Августа 2012
Просмотров: 29646
Правила перепечатки

5 последних уроков рубрики «PHP»

Фильтрация данных с помощью zend-filter

Когда речь идёт о безопасности веб-сайта, то фраза "фильтруйте всё, экранируйте всё" всегда будет актуальна. Сегодня поговорим о фильтрации данных.

Контекстное экранирование с помощью zend-escaper

Обеспечение безопасности веб-сайта — это не только защита от SQL инъекций, но и протекция от межсайтового скриптинга (XSS), межсайтовой подделки запросов (CSRF) и от других видов атак. В частности, вам нужно очень осторожно подходить к формированию HTML, CSS и JavaScript кода.

Подключение Zend модулей к Expressive

Expressive 2 поддерживает возможность подключения других ZF компонент по специальной схеме. Не всем нравится данное решение. В этой статье мы расскажем как улучшили процесс подключение нескольких модулей.

Совет: отправка информации в Google Analytics через API

Предположим, что вам необходимо отправить какую-то информацию в Google Analytics из серверного скрипта. Как это сделать. Ответ в этой заметке.

Подборка PHP песочниц

Подборка из нескольких видов PHP песочниц. На некоторых вы в режиме online сможете потестить свой код, но есть так же решения, которые можно внедрить на свой сайт.

Создание API-ориентированного веб-приложения.

Планируете начать работу над новым веб-приложением? В этом уроке мы рассмотрим, как создать API-ориентированное веб-приложение, и объясним, почему это необходимо в современном мульти-платформенном мире .

Введение

Для тех, кто не знаком с термином, API является сокращением от Application Programming Interface(Интерфейс прикладного программирования). Согласно Википедии :

Интерфейс программирования приложений (англ. application programming interface) — набор готовых классов, процедур, функций, структур и констант, предоставляемых приложением (библиотекой, сервисом) для использования во внешних программных продуктах. Используется программистами для написания всевозможных приложений.

API

Визуализация API
Изображение предоставлено https://blog.zoho.com

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

Что такое API-ориентированное веб-приложение?

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

Другой характерной особенностью API-ориентированного веб-приложения является то, что API не зависит от состояния пользователя. Это ограничение на самом деле хорошее — это «заставляет» разработчика создавать API, который не зависит от текущего состояния пользователя, а представляет собой чистую функциональность, что, в свою очередь, облегчает тестирование, так как текущее состояние пользователя не нужно имитировать.

Зачем все это нужно?

Время не стоит на месте. Общеизвестно, что люди сегодня используют приложения не только через браузер, но и с помощью других устройств, например мобильных телефонов и планшетов. Например, в статьe на Mashable “Consumers Now Spending More Time on Mobile Apps Than the Web” , говорится:

Потребители впервые начали тратить больше времени на мобильныe приложения, чем на веб-серфинг.

Flurry сравнивали свои данные статистики по мобильным приложениям от ComScore и Алекса, и обнаружили, что в июне пользователи потратили 81 минуту в день на мобильные приложения и только 74 минуты веб-серфинг.

Вот статья ReadWriteWeb «More People Browse On Mobile Than Use IE6 & IE7 Combined» :

Последние данные о тенденциях браузеров от Sitepoint показывают, что количество людей, просматриваюших веб-страницы на смартфонах больше количества пользователей Internet Explorer 6 и 7 вместе взятых. Эти два старых драндулета были комком геморроя для веб-разработчиков в течение многих лет, требуя разрабатывать деградацию для сайтов. Но все изменилось сейчас; 6,95% веб-активности в ноябре 2011 года была на мобильных браузерах, и только 6,49% было на IE 6 или 7.

Очевидно, все больше и больше людей получают новости нанапрямую с сайтов а, в частности, с мобильных устройств.

Какое это имеет отношение к созданию API-ориентированного веб-приложения?

Это неизбежно приведет к более частому использованию нашего приложения, так как он может использоваться на любом устройстве и платформе.

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

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

Вот статья о редизайне сайта Твиттера , в которой рассказыватеся о том, как они теперь используют их API на сайте Twitter.com, по сути делая его API-ориентированным:

Одним из самых значительных архитектурных изменений является то, что Twitter.com сейчас является пользователем нашего собственного API. Он извлекает данные так же как и мобильный сайт, наши приложения для iPhone, iPad, Android, и любое другое приложение стороннего использования. Это изменение позволило нам выделить больше ресурсов для команды API. При первоначальной загрузки страницы и при каждом запросе клиента, все данные теперь извлекаются из оптимизированного кэша.

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

Шаг 1: Планирование функциональности приложения

В TODO приложении, которое мы будем делать будут реализованы основные CRUD функции:

Создание TODO элементов
Чтение TODO элементов
Обновление TODO элементов (переименование, отметить как «выполнено», пометить как «не выполнено»)
Удаление TODO элементов

Каждый пункт будет иметь:

Название
Дата окончания
Описание
Флаг, означающий, что дело сделано

Давайте нарисуем макет разрабатываемого нами приложения:

Шаг 2: Создайте Server API

Так как мы разрабатываем API-ориентированное веб-приложение, мы будем создавать две «проекта»: Server API, а клиент. Давайте начнем с создания сервера API.

В папке вашего веб-сервера создайте папку с именем simpletodo_api , с файлом index.php . Это файл будет выступать в качестве фронт-контроллера для API, так что все запросы к серверу API будет осуществляться через этот файл. Откройте его и поместите следующий код:

Это контроллер фронт, который выполняет следующие действия:

Принимает вызовы API с любым числом параметров
Извлекает Controller и Action для вызова API
Проводит необходимые проверки, чтобы убедиться, что Controller и Action существуют
Выполняет вызов API
Отлавливает ошибки, если таковые имеются
Отправляет результат пользователю

Помимо файла index.php , создайте три папки: controllers, models и data .

Папка controllers будет содержать все контроллеры, которые мы будем использовать для сервера API. Мы будем создавать их, используя архитектуру MVC , чтобы сделать структуру сервера API более чистой и структурированной.
Папка models будет содержать все модели данных для сервера API.
Папка data создана для хранения любых данных.

Перейти в папку контроллеров и создает файл под названием Todo.php . Это будет наш контроллер для решения задач, связанных с TODO списками. Создаем заготовку класса и функций для нашего приложения:

Теперь добавьте необходимую функциональность для каждого action . Я приведу код для метода createAction . За вами остается написание кода для других методов. Если вы не в настроении, вы можете просто скачать исходный код демо.

Создайте TodoItem.php внутри папки models , чтобы мы могли создать код, реализующий «создание пункта списка». Примите к сведению, что я не будут подключаться к базе данных, я буду сохранения информацию в файлы. Он должен быть относительно легко.

createAction метод вызывает две функции модели TodoItem :

save() — сохранение TodoItem в файл, а также при необходимости создает todo_id для TodoItem .
ToArray () — возвращает TodoItem в виде массива, индексами которого служат названия переменных.

Поскольку API вызывается через запросы HTTP, давайте проверим API-вызовов, вызвав его через браузер:

Если все работает, вы должны увидеть новую папку внутри папки data , и внутри этой папки, Вы должны увидеть файл со следующим содержанием:

Поздравляем! Вы успешно создали сервер API и сделали вызов API!

Шаг 3: Обеспечение безопасности API сервера при помощи APP ID и APP SECRET

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

Начнем с создания пары id-ключ для клиентов, которые будут использовать сервер API. Так как это всего лишь демо, мы можем использовать любую случайную, 32 символьную строку. Для APP ID , примем что это приложение APP001.

Откройте файл index.php еще раз, а затем обновите его следующим кодом:

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

Шифрование с открытым ключом

API вызов сделан, в нем предоставляется $ APP_ID и $ enc_request .
$ enc_request содержит параметры вызова API, зашифрованные с помощью APP KEY . APP KEY никогда не отправляется на сервер, он используется только для шифрования запроса. Кроме того, запрос может быть расшифровано только с помощью APP KEY .
Когда вызов API приходит на сервер API, то сервер проверять свой собственный список приложений на наличие APP ID .
При такое приложение обнаружено, то сервер API пытается расшифровать запрос, используя ключ, который соответствует APP ID .
Если она расшифровка была успешной, то продолжаем работать с программой.

Теперь, когда сервер API защищен APP ID и APP SECRET , мы можем приступать к программированию тонкого клиента.

Шаг 4: Создание тонкого клиента

Мы начнем с создания новой папки для тонкого клиента. Создайте папку с именем simpletodo_client_browser в папке веб-сервера. После этого, создайте файл index.php и поместите этот код в него:

Это должно выглядеть примерно так:

SimpleTODO страница авторизации

Обратите внимание, что я включил 2 JS и 2 CSS файла:

reset.css стандартный CSS Reset.
bootstrap.min.css это Twitter Bootstrap
jquery.min.js последняя версия JQuery
JQuery-ui-1.8.16.custom.min.js последняя версия JQuery UI

Далее, давайте создадим файл login.php , для хранения имени пользователя и пароля.

Здесь мы просто создаем сессию для пользователя, в которой храняться имя пользователя и пароль. Эта пара представляет собой составной ключ по которому мы можем получить доступ к хранящимся TODO спискам. Потом мы перенаправляем пользователя на страницу todo.php для начала взаимодействия с API сервером. Прежде чем мы начнем писать код в файл todo.php , давайте сначала создадим класс ApiCaller, который будет инкапсулировать все методы вызова API, которые нам понадобится, включая шифрование запросов.

Создайте apicaller.php и скопируйте следующий код:

Мы будем использовать класс ApiCaller для отправки запросов к нашему API серверу . Таким образом, все необходимое шифрование и инициализация CURL будет в одном месте, и мы не должны повторять наш код.

__construct функция принимает три параметра:
1. $ APP_ID — APP ID для клиента (который APP001 для браузера)
2. $ App_key — APP KEY для клиента (28e336ac6c9423d946ba02d19c6a2632 для браузера )
3. $ Api_url — URL сервера API, https://localhost/simpletodo_api/
функция sendRequest() :
1. шифрует параметры запроса, используя библиотеку mcrypt в том же порядке, что сервер API расшифровывает его
2. генерирует параметры $_POST , которые будут отправлены на сервер API
3. выполняет вызов API через CURL
4. проверяет результат вызова API был успешным или нет
5. возвращает данные, когда все прошло успешно

Теперь, давайте разберемся со страницей todo.php . Во-первых, давайте создадим какой-то код, чтобы получить текущий список TODO для пользователя nikko с паролем test1234 (эту комбинацию имени пользователя / пароля мы использовали ранее для тестирования сервера API).

Вернитесь к файлу index.php , войдите как nikko/test1234, и вы должны увидеть var_dump() из TODO, который мы создали ранее.

Поздравляю, вы успешно сделали вызов API к серверу API! В этом коде мы:

создали сессию, таким образом мы имеем доступ к username и userpass в $_SESSION
экземпляр класса ApiCaller , передавая ему APP ID , APP KEY и URL сервера API
отправили запрос через метод sendRequest()

Теперь, давайте переформатируем данные, чтобы они выглядели лучше. Добавьте следующий HTML-код в todo.php . Не забудьте удалить var_dump() !

Это должно выглядеть примерно так:

Довольно прикольно, да? Но это в настоящее время ничего не делает, так что давайте добавим некоторые функциональные возможности. Я приведу код для new_todo.php , который будет вызывать todo/create вызов API , чтобы создать новый пункт TODO. Создание других страниц ( update_todo.php и delete_todo.php ) должно быть очень похоже на создание этой страницы, так что я оставлю это до Вас. Откройте new_todo.php и добавить следующий код:

Как вы можете видеть, страница new_todo.php использует ApiCaller для облегчения отправкиTODO / create запроса к серверу API.

Поздравляем, это работает! Вы успешно создали API-ориентированное веб-приложение!

Заключение

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

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

Планируете ли вы использовать сервер API для вашего следующего веб-приложения, или вы уже использовали ту же самую технику для проекта в прошлом? Дайте мне знать в комментариях!

Как создать API без кода

В данной статье мы покажем как работать с API на нашей no-code платформе уровня pro, AppMaster.io. Но, для начала, напомним немного базовой информации про API.

Вводная информация

API означает Application Programming Interface, программный интерфейс приложения. Это способы, с помощью которых клиент и сервер могут взаимодействовать друг с другом. Клиент и сервер отправляют запросы и ответы, а API выступает посредником между ними.

Важно, чтобы взаимодействие сервера и клиента было легким, понятным и удобным. Это упрощает задачу как разработчиков (не нужно заново изобретать новый сервис), так и пользователей (сервис проще освоить, если он работает по знакомому принципу). Существует несколько видов API:

Web service APIs, XML-RPC, and JSON-RPC, SOAP;
WebSockets APIs;
Library-based APIs, Java Script;
Class-based APIs, C# API, Java.

На no-code платформе AppMaster.io используется стиль REST API.

REST или целиком Representational State Transfer — архитектурный стиль взаимодействия (обмена информацией) между клиентом и сервером. Сервисы в REST API взаимодействуют по протоколу HTTP.

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

Структура любого запроса включает в себя пять основных компонентов: HTTP метод, эндпоинты, заголовки и тело, параметры запроса.

В REST API используются 4 основных HTTP-метода для работы с ресурсом (информацией) и каждый из них описывает, что должно быть сделано с ресурсом:

POST — создание ресурса;
GET — получение ресурса;
PUT — обновление ресурса;
DELETE — удаление ресурса.

Ресурс — это любой вид информации (документ, изображение, видео, текст и так далее). На no-code платформе AppMaster.io эта информация доставляется клиенту в нескольких форматах, в том числе, и в самом распротраненнеом — JSON.

Эндпоинт содержит URI — Uniform Resource Identifier (унифицированный идентификатор ресурса), который указывает, где и как найти ресурс в Интернете и включает в себя URL (URL или Uniform Resource Location является полноценным веб-адресом).

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

Тело необходимо для передачи серверу дополнительной информации: данные тела запроса — это данные, которые вы, например, хотите добавить или заменить.

Документация по API для вашего приложения на нашей платформе создается автоматически и сохраняется в формате OpenAPI (Swagger) в его серверной части.

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

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

Создание API на no-code платформе AppMaster.io

Итак, настройки API вы можете найти в нескольких местах на нашей платформе.

Как создать API Эндпоинт на no-code платформе AppMaster.io

Зайдите в ваш аккаунт, в существующий проект.

Зайдите в Data Model Designer. В нем вы увидите модели с данными, которые хотите обработать с помощью API Эндпоинтов. В каждом проекте на старте всегда по умолчанию есть одна модель — User (Пользователь). Если вы находитесь в новом проекте и у вас еще нет своих моделей, создайте их.

Назначьте связи между вашими моделями и сохраните проект.

Зайдите в раздел Эндпоинты в левом меню экрана.

Здесь вы увидите список всех ваших Эндпоинтов и доступных для них методов REST API, подключенных к каждой модели на поле проекта. Вы сможете удалить ненужные методы и изменить их настройки (значок Шестеренки и значок Корзины).

Если в списке нет подходящего Эндпоинта, вы можете создать новый, нажав на кнопку New Endpoint и выбрав подходящий тип. Откроется модальное окно с настройками Эндпоинта.

Как создать внешний API на no-code платформе AppMaster.io

Зайдите в раздел Business Logic в левом меню.

Здесь вы можете создать внешний API запрос во вкладке External API Request (данная опция находится на стадии бета-тестирования).

Кроме того, как мы и упоминали выше, вся документация формируется автоматически и сохраняется в формате OpenAPI (Swagger) в серверной части вашего приложения.

Но Swagger — это не только документация, а, также, возможность протестировать все Эндпойнты прямо на месте, без использования каких-либо сторонних приложений (например, можно обойтись без Postman).

Создаем наш первый API при помощи Node.js и Express: Разбираемся с REST API

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

В этой серии мы начнем с обзора принципов и понятий REST. Затем мы приступим к созданию нашего собственного полностью работоспособного API, который работает на основе сервера, созданного при помощи Express и Node.js, и подключается к базе данных MySQL. После изучения руководств этой серии вы должны будете чувствовать себя уверенно при создании вашего собственного API или при работе с документацией уже существующего.

Предварительная подготовка

Для того чтобы получить от этого руководства максимум пользы, вы уже должны иметь базовые навыки работы с командной строкой, обладать базовыми знаниями по JavaScript и иметь на своем компьютере установленную глобально Node.js.

Что из себя представляют REST и RESTful API?

При помощи Representational State Transfer (* передача репрезентативного состояния), или REST, описывается архитектурный стиль для веб-сервисов. REST состоит из ряда стандартов или ограничивающих требований по обмену данными между различными системами, и для систем, которые работают согласно принципам REST, используется термин RESTful. REST – абстрактная концепция, это не язык, не фреймворк или тип программного обеспечения.

Для лучшего понимания REST вам могла бы помочь аналогия, когда сравнивается коллекция виниловых пластинок с сервисом для потоковой передачи аудио-данных (* способ воспроизведения аудио- и видеоматериалов из интернета без их предварительного скачивания в компьютер). В случае с виниловыми пластинками для их распространения необходимо, чтобы для каждой записи была создана полная копия. В случае же с сервисом для потоковой передачи аудио-данных та же самая музыка может распространяться неограниченный срок, если известны какие-либо данные, например название песни. В этом случае сервис для потоковой передачи аудио-данных является RESTful сервисом, а коллекция виниловых пластинок – нет.

API (Application Programming Interface) – интерфейс, который позволяет программам общаться друг с другом. RESTful API – просто API, который работает согласно принципам и понятиям REST. В случае с API, работающим в сети, сервер получает запрос при помощи конечной точки, где указан URL-адрес, и отправляет обратно ответ, которым часто являются данные в формате вроде JSON.

Принципы REST

К архитектуре REST выдвигаются шесть основных требований, перечисленных ниже:

Унифицированный интерфейс: интерфейс компонентов должен быть одинаковым. Это достигается за счет использования стандарта URI для идентификации ресурсов – другими словами, путей, которые могли бы быть набраны в адресной строке браузера.
Клиент-Сервер: сервер и клиент выполняют различные задачи: сервер хранит данные и выполняет с ними манипуляции, а клиент отправляет запросы и отображает ответы.
Взаимодействия без запоминания состояния: вся информация о каждом запросе содержится в нем самом и не зависит от состояния сессии.
Возможность использования кэш-памяти: клиент и сервер могут кэшировать ресурсы.
Многоуровневая система: клиент может подключаться к конечному серверу или промежуточному слою вроде компенсатора (* инструмент для эффективного распределения приходящего к группе серверов траффика).
Получение кода по запросу (Не обязательно): клиент может скачать код, за счет чего снижается его видимость в сети.

Запрос и ответ

Вы в курсе, что для всех веб-сайтов используется URL, который начинается с http (или https в случае использования безопасной версии протокола). HyperText Transfer Protocol, или HTTP, – метод коммуникации клиентов с серверами в Интернете.

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

HTTP работает путем открытия соединения TCP (Transmission Control Protocol – протокол управления передачей) к порту сервера ( 80 для http , 443 для https ) для выполнения запроса, а прослушивающий запросы сервер отправляет ответы, в которых содержатся код ответа и тело.

Ответ должен состоять из URL, метода, информации заголовка и тела.

Методы запроса

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

Методы запроса HTTP приблизительно соответствуют парадигме CRUD, что расшифровывается как Create, Update, Read, Delete (* создать, прочесть, обновить, удалить). Хотя CRUD относится к функциям, используемым при выполнении операций над базой данных, мы можем применить те основы конструирования к глаголам HTTP в RESTful API.

Действие	Метод запроса	Определение
Прочитать	GET	При помощи него выполняется получение ресурса
Создать	POST	При помощи него выполняется создание нового ресурса
Обновить	PUT	При помощи него выполняется обновление существующего ресурса
Удалить	DELETE	При помощи него выполняется удаление ресурса

GET – безопасная операция, которая используется только для считывания данных и при выполнении которой состояние сервера не изменится. Каждый раз, когда вы вводите в вашем браузере URL-адрес, например https://www.google.com , вы отправляете запрос по методу GET к серверам Google.

POST используется для создания нового ресурса. Знакомым для вас примером использования POST должна послужить регистрация пользователя на веб-сайте или веб-приложении. После отправления формы на сервер мог бы быть отправлен запрос по методу POST с данными пользователя, где эта информация далее была бы добавлена в базу данных.

При помощи метода PUT существующий ресурс обновляется, что могло бы быть использовано для редактирования настроек существующего пользователя. В отличие от POST PUT – идемпотентный метод. Это означает, что при повторном выполнении запроса будет получаться тот же самый результат. Например если бы вы отправили тот же самый запрос по методу POST для создания нового пользователя в базе данных множество раз, то в результате был бы создан новый пользователь с теми же данными. Однако в результате выполнения того же запроса по методу PUT для того же самого пользователя неизменно выходил бы одинаковый результат.

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

Коды ответа

Как только запрос поступит на сервер, тот отправит ответ HTTP, в котором будут содержаться метаданные об ответе (заголовки) и тело. Первая и наиболее важная часть ответа – код состояния, который указывает на то, был ли запрос выполнен успешно, была ли совершена ошибка при его обработке или же на то, что должно быть выполнено иное действие.

Наиболее известным кодом ответа для вас должен быть 404 , что означает Not Found (* сообщает, что запрашиваемый ресурс не существует на сервере). 404 входит в состав класса 4xx кодов состояния, при помощи которых указывается, что при обработке запроса произошла ошибка. Имеется пять классов кодов состояния, в каждом из которых имеется ряд кодов.

1xx : Information (* Информация о процессе передачи)
2xx : Success (* Информация об успешном принятии и обработке запроса клиента)
3xx : Redirection (* Перенаправление)
4xx : Client Error (* Информация об ошибках со стороны клиента)
5xx : Server Error (* Информация об ошибках со стороны сервера)

Другими распространенными кодами ответов, с которыми вы, скорее всего, знакомы, являются 301 Moved Permanently , который используется для перенаправления браузера по другому URL-адресу, и 500 Internal Server Error , что указывает на то, что при обработке запроса произошла непредвиденная ошибка на стороне сервера, из-за чего текущий запрос не может быть выполнен.

Что касается API RESTful и их соответственных глаголов HTTP, то коды всех ответов должны находиться в диапазоне 2xx .

Запрос	Ответ
GET	200 (OK)
POST	201 (Created) (* Создано)
PUT	200 (OK)
DELETE	200 (OK), 202 (Accepted) (* Принято) или 204 (No Content) (* Нет содержимого; тело сообщения не передается)

200 OK – код ответа, который указывает на то, что запрос был выполнен успешно. Он используется в качестве кода ответа при отправлении запроса по методу GET или PUT . При выполнении запросов по методу POST будет возвращен ответ с кодом состояния 201 Created для указания того, что новый ресурс был создан, и при выполнении запросов по методу DELETE возможны несколько вариантов кодов ответа, благодаря которым подтверждается, что либо запрос был успешно принят ( 202 ), либо отправлять нечего, поскольку ресурс более не существует ( 204 ).

Мы можем протестировать код состояния ответа на запрос ресурса при помощи cURL – инструмента командной строки, который используется для передачи данных при помощи URL-адресов. При помощи команды curl , за которой следует флажок -i или —include будет отправлен запрос по методу GET по указанному URL-адресу и отображены заголовки и тело. Мы можем протестировать это, если откроем консоль и отправим запросы к Google.

Сервера Google пришлют ответ со следующей информацией:

Как видно, в ответ на запрос curl было отправлено множество заголовков и все тело HTML-ответа. Поскольку запрос был выполнен успешно, то первой частью ответа является код состояния 200 вместе с версией HTTP (ею может быть либо HTTP/1.1, либо HTTP/2).

Поскольку в ответ на этот конкретный запрос в ответе приходит веб-сайт, то в качестве значения заголовка content-type (тип MIME (* Multipurpose Internet Mail Extensions – многоцелевые расширения почты (почтовой службы)) указывается text/html . В RESTful API вы, скорее всего, увидите вместо этого application/json , что указывает на то, что форматом ответа является JSON.

Интересно то, что мы можем увидеть иной тип ответа, слегка изменив вводимый URL-адрес. Выполните команду curl для отправления запроса к Google без www .

Google перенаправит клиент на www.google.com , и в ответе будет прислан код состояния 301 для указания того, что должно быть выполнено перенаправление.

Конечные точки RESTful API

Когда API располагается на сервере, то предоставляемые им данные доступны при помощи конечных точек. Конечная точка – отдельная функция API, которая запускается при обращении к серверу по определенному URL-адресу и может принимать и обрабатывать запросы по методу GET , POST , PUT или DELETE .

URL API будет состоять из корня, пути и необязательной строки запроса.

Корень, например https://api.example.com или https://api.example.com/v2 , – корень URL, который может состоять из протокола, домена и версии протокола.
Путь, например /users/ или /users/5 , – уникальное местоположение определенного ресурса.
Параметры запроса (указывать необязательно), например ?location=chicago&age=29 , – необязательные пары ключ=значение, которые используются для сортировки, фильтрации и разбиения контента на страницы.
Мы можем собрать эти компоненты воедино для получения нечто подобного тому, что показано в примере ниже, благодаря чему был бы возвращен список всех пользователей и использован параметр запроса limit для того, чтобы в результате фильтрации в ответ были включены только 10 результатов.

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

Названия путей должны быть указаны во множественном числе: например для того чтобы получить данные о пользователе с id 5 , мы бы воспользовались /users/5 , а не /user/5 .
В URL не должно содержаться расширения файла: несмотря на то что при обращении к конечной точке API, скорее всего, будет возвращаться файл в формате JSON, URL не должен оканчиваться на .json .
В URL должны использоваться существительные, а не глаголы: слова вроде add и delete не должны содержаться в URL, используемом в RESTful API. Для добавления нового пользователя вы могли бы просто отправить POST -запрос по адресу, в котором используется /users , а не что-то вроде /users/add . API должен разрабатываться так, чтобы был способен обрабатывать различные типы запросов по тому же самому URL-адресу.
Пути чувствительны к регистру (заглавным или строчным буквам) и должны быть написаны в нижнем регистре с использованием дефисов, а не символов подчеркивания.

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