У семерых козлов и волк без глазу
Создание RESTful API на PHP
REST или в полной форме, Representational State Transfer стало стандартной архитектурой проектирования для разработки веб-API.
REST является очень простым интерфейсом управления информацией без использования каких-то дополнительных внутренних прослоек. Каждая единица информации однозначно определяется глобальным идентификатором, таким как URL. Каждая URL в свою очередь имеет строго заданный формат.
REST использует методы HTTP-запроса, чтобы скомпоновать себя в существующую архитектуру HTTP. Эти операции состоят в следующем:
GET - используется для базовых запросов на чтение на сервер
PUT- Используется для изменения существующего объекта на сервере
POST- Используется для создания нового объекта на сервере
DELETE - используется для удаления объекта на сервере
А теперь к сути, т.е. написанию простого API, который вы можете использовать в своих проектах.
Что такое API
В широком смысле API - это интерфейс веб-приложения, позволяет публично использовать методы для доступа и управления извне. Обычное использование API - это когда необходимо получать данные из приложения (например, статья или какие-то другие данные) без фактического посещения ресурса (например сайта). Чтобы сделать это возможным, для приложения реализуется API, который позволяет сторонним приложениям совершать запросы и возвращать указанные данные пользователю извне. В Интернете это часто делается с использованием RESTful.
В примере запроса статьи API может содержать URI:
example.com/api/v1/recipe/article
Если отправить запрос GET в этот URL, ответ может быть списком самых последних новостей, запрос PUT может добавить новость в БД.
Если запросить /article /141, то это будет определенная новость. Это примеры показывают способ взаимодействия с приложением.
Создание своего API
Создадим файл.htaccess для того чтобы GET запросы преобразовывать в понятные контроллеру параметры.
Что же означают строки этого файла?
В первой строке проверяется существование модуля rewrite. Если он запущен, выполняются следующие строки.
Далее объявляется возможность переопределять URL. Это значит, что путь api/v1/ будет перенаправлен на api/v1/index.php. Символы (.*) обозначают переменные, которые необходимо обработать а $ - это ограничитель, после которого начинается следующая логика. Также, - означает нечувствительность к регистру, - что переменные будут присоединены к новому URL, L - mod_rewrite больше не обрабатывает ничего кроме указанного.
Объявляем класс, свойства и конструктор.
abstract class API
{
/**
* Property: method
* GET, POST, PUT, DELETE
*/
protected $method = "";
/**
* Property: endpoint
* The Model requested in the URI. eg: /files
*/
protected $endpoint = "";
/**
* Property: verb
* An optional additional descriptor about the endpoint, used for things that can
* not be handled by the basic methods. eg: /files/process
*/
protected $verb = "";
/**
* Property: args
* Any additional URI components after the endpoint and verb have been removed, in our
* case, an integer ID for the resource. eg: /
Объявив этот абстрактный класс, мы запретили PHP создавать конкретный экземпляр этого класса. Оттуда мы можем только использовать методы, унаследовав в другом классе. Защищенный метод может быть доступен только в самом классе и его потомках.
Создание класса API
Создаем классMyAPI который наследует абстрактный класс API.
require_once "API.class.php"; class MyAPI extends API { protected $User; public function __construct($request, $origin) { parent::__construct($request); // Abstracted out for example $APIKey = new Models\APIKey(); $User = new Models\User(); if (!array_key_exists("apiKey", $this->request)) { throw new Exception("No API Key provided"); } else if (!$APIKey->verifyKey($this->request["apiKey"], $origin)) { throw new Exception("Invalid API Key"); } else if (array_key_exists("token", $this->request) && !$User->get("token", $this->request["token"])) { throw new Exception("Invalid User Token"); } $this->User = $User; } /** * Example of an Endpoint */ protected function example() { if ($this->method == "GET") { return "Your name is " . $this->User->name; } else { return "Only accepts GET requests"; } } }
Использование API
// Requests from the same server don"t have a HTTP_ORIGIN header if (!array_key_exists("HTTP_ORIGIN", $_SERVER)) { $_SERVER["HTTP_ORIGIN"] = $_SERVER["SERVER_NAME"]; } try { $API = new MyAPI($_REQUEST["request"], $_SERVER["HTTP_ORIGIN"]); echo $API->processAPI(); } catch (Exception $e) { echo json_encode(Array("error" => $e->getMessage())); }
Корявый перевод этого: http://coreymaynard.com/blog/creating-a-restful-api-with-php/
Не так давно один из моих посетителей мне задал вопрос по e-mail : "". Я решил, что это будет весьма полезно другим пользователям, тем более, что на кажущуюся сложность процесса, всё очень и очень просто. Необходимо лишь обладать самыми элементарными знаниями PHP .
Если Вы вдруг не понимаете, о чём идёт речь, то прочитайте сначала статью: . Идём дальше. Давайте разберём, а для каких сайтов нужен вообще API :
Первое, что необходимо усвоить - это то, что API нужен далеко не каждому сайту (даже если он принадлежит одной из вышеуказанных групп).
Если же Вы считаете, что API на Вашем сайте необходим, то давайте разберём пример того, как он создаётся. Пусть у нас будет такая задача: есть ЭПС (как, например, WebMoney ). И мы хотим, чтобы пользователь мог из своего кода, пользуясь нашим API , узнать свой баланс на счёте.
Создадим файл (например, api.php ), который у нас будет принимать GET-запросы от пользователей на получение различной информации. Напишем в этом обработчике такой код:
if ($_GET["action"] == "getbalance") {
$balance;
//Узнаём из базы данных баланс аккаунта и записываем в переменную balance
echo $balance;
}
?>
Теперь разработчики API должны дать информацию пользователям о том, как надо отправлять запрос, чтобы пользователь мог узнать свой баланс на аккаунте:
Http://mysite.ru/api.php?action=getbalance&key=fa9sgwlgjs9gdsjlgjdsjglsdlgs
Этот запрос пользователи формируют в своих скриптах (например, через cURL ). Параметр key - это уникальный ключ каждого пользователя. И ответом этого запроса будет число, отвечающее за баланс пользователя. Аналогично создаются и все другие возможности API . Можно добавлять другие различные параметры: например, получить список операций пополнения счёта с одной даты по другую. Желательно, сами списки возвращать в формате JSON .
февраль 5 , 2017
Я не знаю ни одного php-фреймворка. Это печально и стыдно, но законом пока не запрещено. А при этом поиграться с REST API хочется. Проблема в том, что php по умолчанию поддерживает только $_GET и $_POST. А для RESTful-сервиса надобно уметь работать еще и с PUT, DELETE и PATCH. И не очень очевидно, как культурно обработать множество запросов вида GET http://site.ru/users, DELETE http://site.ru/goods/5 и прочего непотребства. Как завернуть все подобные запросы в единую точку, универсально разобрать их на части и запустить нужный код для обработки данных?
Почти любой php-фреймворк умеет делать это из коробки. Например, Laravel, где роутинг реализован понятно и просто. Но что если нам не нужно прямо сейчас заниматься изучением новой большой темы, а хочется просто быстро завести проект с поддержкой REST API? Об этом и пойдет речь в статье.
Что должен уметь наш RESTful-сервис?
1. Поддерживать все 5 основных типов запросов: GET, POST, PUT, PATCH, DELETE.
2. Разруливать разнообразные маршруты вида
POST /goods
PUT /goods/{goodId}
GET /users/{userId}/info
и прочие сколь угодно длинные цепочки.
Внимание: это статья не про основы REST API
Я предполагаю, что Вы уже знакомы с REST-подходом и понимаете, как это работает.
Если нет, то в интернетах много замечательных статей по основам REST -
я не хочу дублировать их, моя идея - показать, как с REST работать на практике.
Какой функционал мы будем поддерживать?
Рассмотрим 2 сущности - товары и пользователи.
Для товаров возможности следующие:
- 1. GET /goods/{goodId} — Получение информации о товаре
- 2. POST /goods — Добавление нового товара
- 3. PUT /goods/{goodId} — Редактирование товара
- 4. PATCH /goods/{goodId} — Редактирование некоторых параметров товара
- 5. DELETE /goods/{goodId} — Удаление товара
По пользователям для разнообразия рассмотрим несколько вариантов с GET
- 1. GET /users/{userId} — Полная информация о пользователе
- 2. GET /users/{userId}/info — Только общая информация о пользователе
- 3. GET /users/{userId}/orders — Список заказов пользователя
Как это заработает на нативном PHP?
Первое, что мы сделаем - это настроим.htaccess так, чтобы все запросы перенаправлялись на файл index.php. Именно он и будет заниматься извлечением данных.
Второе - определимся, какие данные нам нужны и напишем код для их получения - в index.php.
Нас интересуют 3 типа данных:
- 1. Метод запроса (GET, POST, PUT, PATCH или DELETE)
- 2. Данные из URL-a, например, users/{userId}/info - нужны все 3 параметра
- 3. Данные из тела запроса
.htaccess
Создадим в корне проекта файл.htaccess
RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.+)$ index.php?q=$1
Этими загадочными строками мы повелеваем делать так:
1 - направить все запросы любого вида на царь-файл index.php
2 - сделать строку в URL-е доступной в index.php в get-параметре q.
То есть данные из URL-а вида /users/{userId}/info
мы достанем из $_GET["q"].
index.php
Рассмотрим index.php строка за строкой. Для начала получим метод запроса.
// Определяем метод запроса $method = $_SERVER["REQUEST_METHOD"];
Затем данные из тела запроса
// Получаем данные из тела запроса $formData = getFormData($method);
Для GET и POST легко вытащить данные из соответствующих массивов $_GET и $_POST. А вот для остальных методов нужно чуть извратиться. Код для них вытаскивается из потока php://input , код легко гуглится, я всего лишь написал общую обертку - функцию getFormData($method)
// Получение данных из тела запроса function getFormData($method) { // GET или POST: данные возвращаем как есть if ($method === "GET") return $_GET; if ($method === "POST") return $_POST; // PUT, PATCH или DELETE $data = array(); $exploded = explode("&", file_get_contents("php://input")); foreach($exploded as $pair) { $item = explode("=", $pair); if (count($item) == 2) { $data = urldecode($item); } } return $data; }
То есть мы получили нужные данные, скрыв все детали в getFormData - ну и отлично. Переходим к самому интересному - роутингу.
// Разбираем url $url = (isset($_GET["q"])) ? $_GET["q"] : ""; $url = rtrim($url, "/"); $urls = explode("/", $url);
Выше мы узнали, что.htaccess подложит нам параметры из URL-a в q-параметр массива $_GET. То есть в $_GET["q"] попадет примерно такая строка: users/10 . Независимо от того, каким методом мы запрос дергаем.
А explode("/", $url)
преобразует нам эту строку в массив, с которым уже можно работать.
Таким образом, составляйте сколько угодно длинные цепочки запросов, например,
GET /goods/page/2/limit/10/sort/price_asc
И будьте уверены, получите массив
$urls = array("goods", "page", "2", "limit", "10", "sort", "price_asc");
Теперь у нас есть все данные, нужно сделать с ними что-нибудь полезное. А сделают это всего лишь 4 строки кода
// Определяем роутер и url data $router = $urls; $urlData = array_slice($urls, 1); // Подключаем файл-роутер и запускаем главную функцию include_once "routers/" . $router . ".php"; route($method, $urlData, $formData);
Улавливаете? Мы заводим папку routers, в которую складываем файлы, манипулирующие одной сущностью: товарами или пользователями. При этом договариваемся, что название файлов совпадают с первым параметром в urlData - он и будет роутером, $router. А из urlData этот роутер нужно убрать, он нам больше не нужен и используется только для подключения нужного файла. array_slice($urls, 1) и вытащит нам все элементы массива, кроме первого.
Теперь осталось подключить нужный файл-роутер и запустить функцию route с тремя параметрами. Что же это за function route? Условимся, что в каждом файле-роутере будет определена такая функция, которая по входным параметрам определит, какое действие инициировал пользователь, и выполнит нужный код. Сейчас это станет понятнее. Рассмотрим первый запрос - получение данных о товаре.
GET /goods/{goodId}
Файл routers/goods.php
// Роутер function route($method, $urlData, $formData) { // Получение информации о товаре // GET /goods/{goodId} if ($method === "GET" && count($urlData) === 1) { // Получаем id товара $goodId = $urlData; // Вытаскиваем товар из базы... // Выводим ответ клиенту echo json_encode(array("method" => "GET", "id" => $goodId, "good" => "phone", "price" => 10000)); return; } // Возвращаем ошибку header("HTTP/1.0 400 Bad Request"); echo json_encode(array("error" => "Bad Request")); }
Содержимое файла - это одна большая функция route, которая в зависимости от переданных параметров выполняет нужные действия. Если метод GET и в urlData передан 1 параметр (goodId), то это запрос о получении данных о товаре.
Внимание: пример очень упрощенный
В реале, конечно же, нужно дополнительно проверять входные параметры, например, что goodId - это число.
Вместо того, чтобы писать код здесь, Вы, вероятно, подключите нужный класс.
И для получения товара создадите объект оного класса и вызовете у него какой-то метод.
А может быть, передадите управление какому-то контроллеру, который уже озаботится инициализацией нужных моделей.
Вариантов много, мы рассматриваем только общую структуру кода.
В ответе клиенту мы выводим нужные данные: название товара и его цену. id товара и метод в реальном приложении совершенно не обязательны. Покажем их только, чтобы убедится, что вызывается нужный метод с правильными параметрами.
Давайте попробуем на примере: откройте консоль браузера и выполните код
$.ajax({url: "/examples/rest/goods/10", method: "GET", dataType: "json", success: function(response){console.log("response:", response)}})
Код отправит запрос на сервер, где я развернул подобное приложение и выведет ответ.
Убедитесь, что интересующий наш маршрут /goods/10
действительно отработал.
На вкладке Network Вы заметите такой же запрос.
И да, /examples/rest - это корневой путь нашего тестового приложения на сайт
Если Вам привычнее пользоваться curl-ом в консоли, то запустите в терминале это - ответ будет тот же самый, да еще и с заголовками от сервера.
Curl -X GET https://сайт/examples/rest/goods/10 -i
В конце функции мы написали такой код.
// Возвращаем ошибку header("HTTP/1.0 400 Bad Request"); echo json_encode(array("error" => "Bad Request"));
Он значит, что если мы ошиблись с параметрами или запрашиваемый маршрут не определен, то вернем клиенту 400-ю ошибку Bad Request. Добавьте, например, к URL-у что-то вроде goods/10/another_param и увидите ошибку в консоли и ответ 400 - кривой запрос не прошел.
По http-кодам ответов сервера
Мы не будем заморачиваться с выводом разных кодов, хотя по REST-у это и стоит делать.
Клиентских ошибок много. Даже в нашем простом случае уместна 405 в случае неправильно переданного метода.
Намеренно не хочу усложнять.
В случае успеха сервер у нас всегда вернет 200 ОК.
По хорошему, при создании ресурса стоит отдавать 201 Created.
Но опять-таки в плане упрощения эти тонкости мы отбросим, а в реальном проекте Вы их легко реализуете сами.
По совести говоря, статья закончена. Думаю, Вы уже поняли подход, каким образом разруливаются все маршруты, вынимаются данные, как это протестировать, как добавлять новые запросы и т.д. Но я для завершения образа приведу реализацию оставшихся 7 запросов, которые мы обозначили в начале статьи. Попутно приведу пару интересных замечаний, а в конце выложу архив с исходниками.
POST /goods
Добавление нового товара
// Добавление нового товара // POST /goods if ($method === "POST" && empty($urlData)) { // Добавляем товар в базу... // Выводим ответ клиенту echo json_encode(array("method" => "POST", "id" => rand(1, 100), "formData" => $formData)); return; }
urlData сейчас пустой, но зато используется formData - мы ее просто выведем клиенту.
Как сделать "правильно"?
Согласно канонам REST в post-запросе следует отдавать обратно только id созданной сущности или url, по которому эту сущность можно получить.
То есть в ответе будет или просто число - {goodId}
, или /goods/{goodId}
.
Почему я написал "правильно" в кавычках? Да потому, что REST - это набор не жестких правил, а рекомендаций.
И как будете реализовывать именно Вы, зависит от Ваших предпочтений или уже принятых соглашений на конкретном проекте.
Просто имейте в виду, что другой программист, читающий код и осведомленный о REST-подходе,
будет ожидать в ответе на post-запрос id созданного объекта или url, по которому можно get-запросом вытащить данные об этом объекте.
Тестим из консоли
$.ajax({url: "/examples/rest/goods/", method: "POST", data: {good: "notebook", price: 20000}, dataType: "json", success: function(response){console.log("response:", response)}})
Curl -X POST https://сайт/examples/rest/goods/ --data "good=notebook&price=20000" -i
PUT /goods/{goodId}
Редактирование товара
// Обновление всех данных товара // PUT /goods/{goodId} if ($method === "PUT" && count($urlData) === 1) { // Получаем id товара $goodId = $urlData; // Обновляем все поля товара в базе... // Выводим ответ клиенту echo json_encode(array("method" => "PUT", "id" => $goodId, "formData" => $formData)); return; }
Здесь уже все данные используются по-полной. Из urlData вытаскивается id товара, а из formData - свойства.
Тестим из консоли
$.ajax({url: "/examples/rest/goods/15", method: "PUT", data: {good: "notebook", price: 20000}, dataType: "json", success: function(response){console.log("response:", response)}})
Curl -X PUT https://сайт/examples/rest/goods/15 --data "good=notebook&price=20000" -i
PATCH /goods/{goodId}
Частичное обновление товара
// Частичное обновление данных товара // PATCH /goods/{goodId} if ($method === "PATCH" && count($urlData) === 1) { // Получаем id товара $goodId = $urlData; // Обновляем только указанные поля товара в базе... // Выводим ответ клиенту echo json_encode(array("method" => "PATCH", "id" => $goodId, "formData" => $formData)); return; }
Тестим из консоли
$.ajax({url: "/examples/rest/goods/15", method: "PATCH", data: {price: 25000}, dataType: "json", success: function(response){console.log("response:", response)}})
Curl -X PATCH https://сайт/examples/rest/goods/15 --data "price=25000" -i
К чему эти понты с PUT и PATCH?
Разве одного PUT не достаточно? Разве не выполняют они одно и то же действие - обновляют данные объекта?
Именно так - внешне действие одно. Разница в передаваемых данных.
PUT предполагает, что на сервер передаются все
поля объекта, а PATCH - только измененные
.
Те, которые переданы в теле запроса.
Обратите внимание, что в предыдущем PUT мы передали и название товара, и цену.
А в PATCH - только цену. То есть мы отправили на сервер только измененные данные.
Нужен ли Вам PATCH - решайте сами. Но помните о том читающем код программисте, о котором я упоминал выше.
DELETE /goods/{goodId}
Удаление товара
// Удаление товара // DELETE /goods/{goodId} if ($method === "DELETE" && count($urlData) === 1) { // Получаем id товара $goodId = $urlData; // Удаляем товар из базы... // Выводим ответ клиенту echo json_encode(array("method" => "DELETE", "id" => $goodId)); return; }
Тестим из консоли
$.ajax({url: "/examples/rest/goods/20", method: "DELETE", dataType: "json", success: function(response){console.log("response:", response)}})
Curl -X DELETE https://сайт/examples/rest/goods/20 -i
С DELETE-запросом все понятно. Теперь давайте рассмотрим работу с пользователями - роутер users и соответственно, файл users.php
GET /users/{userId}
Получение всех данных о пользователе. Если GET-запрос вида /users/{userId} , то мы вернем всю информацию о пользователе, если дополнительно указывается /info или /orders , то соответственно, только общую информацию или список заказов.
// Роутер function route($method, $urlData, $formData) { // Получение всей информации о пользователе // GET /users/{userId} if ($method === "GET" && count($urlData) === 1) { // Получаем id товара $userId = $urlData; // Вытаскиваем все данные о пользователе из базы... // Выводим ответ клиенту echo json_encode(array("method" => "GET", "id" => $userId, "info" => array("email" => "[email protected]", "name" => "Webdevkin"), "orders" => array(array("orderId" => 5, "summa" => 2000, "orderDate" => "12.01.2017"), array("orderId" => 8, "summa" => 5000, "orderDate" => "03.02.2017")))); return; } // Возвращаем ошибку header("HTTP/1.0 400 Bad Request"); echo json_encode(array("error" => "Bad Request")); }
Тестим из консоли
$.ajax({url: "/examples/rest/users/5", method: "GET", dataType: "json", success: function(response){console.log("response:", response)}})
Curl -X GET https://сайт/examples/rest/users/5 -i
GET /users/{userId}/info
Общая информация о пользователе
// Получение общей информации о пользователе // GET /users/{userId}/info if ($method === "GET" && count($urlData) === 2 && $urlData === "info") { // Получаем id товара $userId = $urlData; // Вытаскиваем общие данные о пользователе из базы... // Выводим ответ клиенту echo json_encode(array("method" => "GET", "id" => $userId, "info" => array("email" => "[email protected]", "name" => "Webdevkin"))); return; }
Тестим из консоли
$.ajax({url: "/examples/rest/users/5/info", method: "GET", dataType: "json", success: function(response){console.log("response:", response)}})
Curl -X GET https://сайт/examples/rest/users/5/info -i
GET /users/{userId}/orders
Получение списка заказов пользователя
// Получение заказов пользователя // GET /users/{userId}/orders if ($method === "GET" && count($urlData) === 2 && $urlData === "orders") { // Получаем id товара $userId = $urlData; // Вытаскиваем данные о заказах пользователя из базы... // Выводим ответ клиенту echo json_encode(array("method" => "GET", "id" => $userId, "orders" => array(array("orderId" => 5, "summa" => 2000, "orderDate" => "12.01.2017"), array("orderId" => 8, "summa" => 5000, "orderDate" => "03.02.2017")))); return; }
Тестим из консоли
$.ajax({url: "/examples/rest/users/5/orders", method: "GET", dataType: "json", success: function(response){console.log("response:", response)}})
Curl -X GET https://сайт/examples/rest/users/5/orders -i
Итоги и исходники
Исходники из примеров статьи -
Как видим, организовать поддержку REST API на нативном php оказалось не так уж и сложно и вполне законными способами. Главное - это поддержка маршрутов и нестандартных для php методов PUT, PATCH и DELETE.
Основной код, реализовывающий эту поддержку, уместился в 3 десятка строк index.php. Остальное - это уже обвязка, которую можно реализовать как угодно. Я предложил это сделать в виде подключаемых файлов-роутеров, имена которых совпадают с сущностями Вашего проекта. Но можно подключить фантазию и найти более интересное решение.
Разрабатывая проект, я столкнулся с необходимостью организации клиент-серверного взаимодействия приложений на платформах iOS и Android с моим сайтом на котором хранилась вся информация - собственно БД на mysql, картинки, файлы и другой контент.
Задачи которые нужно было решать - достаточно простые:
регистрация/авторизация пользователя;
отправка/получение неких данных (например список товаров).
И тут-то мне захотелось написать свой API для взаимодействия с серверной стороной - большей своей частью для практического интереса.
Входные данные
В своем распоряжении я имел:
Сервер - Apache, PHP 5.0, MySQL 5.0
Клиент - Android, iOS устройства, любой браузер
Я решил, что для запросов к серверу и ответов от него буду использовать JSON формат данных - за его простоту и нативную поддержку в PHP и Android. Здесь меня огорчила iOS - у нее нет нативной поддержки JSON (тут пришлось использовать стороннюю разработку).
Так же было принято решение, что запросы можно будет отсылать как через GET так и через POST запросы (здесь помог $_REQUEST в PHP). Такое решение позволило проводить тестирование API через GET запросы в любом доступном браузере.
Внешний вид запросов решено было сделать таким:
http://[адрес сервера]/[путь к папке api]/?[название_api].[название_метода]=
Путь к папке api - каталог на который нужно делать запросы, в корне которого лежит файл index.php - он и отвечает за вызов функций и обработку ошибок
Название api - для удобства я решил разделить API группы - пользователь, база данных, конент и тд. В таком случае каждый api получил свое название
Название метода - имя метода который нужно вызвать в указанном api
JSON - строковое представление JSON объекта для параметров метода
Скелет API
Скелет API на серверной стороне состоит из нескольких базовых классов:
index.php - индексный файл каталога в Apache на него приходятся все вызовы API, он осуществляет парсинг параметров и вызов API методов
MySQLiWorker - класс-одиночка для работы с базой MySQL через MySQLi
apiBaseCalss.php - родительский класс для всех API в системе - каждый API должен быть наследован от этого класса для корректной работы
apiEngine.php - основной класс системы - осуществляет разбор переданных параметров (после их предварительного парсинга в index.php) подключение нужного класса api (через require_once метод), вызов в нем нужного метода и возврат результата в JSON формате
apiConstants.php - класс с константами для api вызовов и передачи ошибок
apitest.php - тестовый api для тестирования новых методов перед их включением в продакшн версию
Весь механизм выглядит следующим образом:
Мы делаем запрос на сервер - к примеру www.example.com/api/?apitest.helloWorld= {}
На серверной стороне файл index.php - производит парсинг переданных параметров. Index.php берет всегда только первый элемент из списка переданных параметров $_REQUEST - это значит что конструкция вида www.example.com/api/?apitest.helloWorld= {}&apitest.helloWorld2 - произведет вызов только метода helloWorld в apitest. Вызова же метода helloWorld2 непроизойдет
Теперь подробней о каждом
Я попробовал достаточно документировать файлы, чтобы не занимать много место под текст. Однако в тех файлах где нет комментариев, я все ж приведу описание.
Index.php
Как уже говорил раньше это входной индексный файл для Apache а значит все вызовы вида www.example.com/api будет принимать он.
0){ require_once "apiEngine.php"; foreach ($_REQUEST as $apiFunctionName => $apiFunctionParams) { $APIEngine=new APIEngine($apiFunctionName,$apiFunctionParams); echo $APIEngine->callApiFunction(); break; } }else{ $jsonError->error="No function called"; echo json_encode($jsonError); } ?>
Первым делом устанавливаем тип контента - text/html (потом можно сменить в самих методах) и кодировку - UTF-8.
Дальше проверяем, что у нас что-то запрашивают. Если нет то выводим JSON c ошибкой.
Если есть параметры запроса, то подключаем файл движка API - apiEngine.php и создаем класс движка с переданными параметрами и делаем вызов api метода.
Выходим из цикла так как мы решили что будем обрабатывать только один вызов.
apiEngine.php
Вторым по важности является класс apiEngine - он представляет собой движок для вызова api и их методов.
apiFunctionParams = stripcslashes($apiFunctionParams);
//Парсим на массив из двух элементов - название API, - название метода в API
$this->apiFunctionName = explode("_", $apiFunctionName);
}
//Создаем JSON ответа
function createDefaultJson() {
$retObject = json_decode("{}");
$response = APIConstants::$RESPONSE;
$retObject->$response = json_decode("{}");
return $retObject;
}
//Вызов функции по переданным параметрам в конструкторе
function callApiFunction() {
$resultFunctionCall = $this->createDefaultJson();//Создаем JSON ответа
$apiName = strtolower($this->apiFunctionName);//название API проиводим к нижнему регистру
if (file_exists($apiName . ".php")) {
$apiClass = APIEngine::getApiEngineByName($apiName);//Получаем объект API
$apiReflection = new ReflectionClass($apiName);//Через рефлексию получем информацию о классе объекта
try {
$functionName = $this->apiFunctionName;//Название метода для вызова
$apiReflection->getMethod($functionName);//Провераем наличие метода
$response = APIConstants::$RESPONSE;
$jsonParams = json_decode($this->apiFunctionParams);//Декодируем параметры запроса в JSON объект
if ($jsonParams) {
if (isset($jsonParams->responseBinary)){//Для возможности возврата не JSON, а бинарных данных таких как zip, png и др. контетнта
return $apiClass->$functionName($jsonParams);//Вызываем метод в API
}else{
$resultFunctionCall->$response = $apiClass->$functionName($jsonParams);//Вызыаем метод в API который вернет JSON обект
}
} else {
//Если ошибка декодирования JSON параметров запроса
$resultFunctionCall->errno = APIConstants::$ERROR_ENGINE_PARAMS;
$resultFunctionCall->error = "Error given params";
}
} catch (Exception $ex) {
//Непредвиденное исключение
$resultFunctionCall->error = $ex->getMessage();
}
} else {
//Если запрашиваемый API не найден
$resultFunctionCall->errno = APIConstants::$ERROR_ENGINE_PARAMS;
$resultFunctionCall->error = "File not found";
$resultFunctionCall->REQUEST = $_REQUEST;
}
return json_encode($resultFunctionCall);
}
}
?>
apiConstants.php
Данный класс используется только для хранения констант.
MySQLiWorker.php
Класс-одиночка для работы с базой. В прочем это обычный одиночка - таких примеров в сети очень много.
dbName = $dbName; self::$instance->dbHost = $dbHost; self::$instance->dbUser = $dbUser; self::$instance->dbPassword = $dbPassword; self::$instance->openConnection(); } return self::$instance; } //Определяем типы параметров запроса к базе и возвращаем строку для привязки через ->bind function prepareParams($params) { $retSTMTString = ""; foreach ($params as $value) { if (is_int($value) || is_double($value)) { $retSTMTString.="d"; } if (is_string($value)) { $retSTMTString.="s"; } } return $retSTMTString; } //Соединяемся с базой public function openConnection() { if (is_null($this->connectLink)) { $this->connectLink = new mysqli($this->dbHost, $this->dbUser, $this->dbPassword, $this->dbName); $this->connectLink->query("SET NAMES utf8"); if (mysqli_connect_errno()) { printf("Подключение невозможно: %s\n", mysqli_connect_error()); $this->connectLink = null; } else { mysqli_report(MYSQLI_REPORT_ERROR); } } return $this->connectLink; } //Закрываем соединение с базой public function closeConnection() { if (!is_null($this->connectLink)) { $this->connectLink->close(); } } //Преобразуем ответ в ассоциативный массив public function stmt_bind_assoc(&$stmt, &$out) { $data = mysqli_stmt_result_metadata($stmt); $fields = array(); $out = array(); $fields = $stmt; $count = 1; $currentTable = ""; while ($field = mysqli_fetch_field($data)) { if (strlen($currentTable) == 0) { $currentTable = $field->table; } $fields[$count] = &$out[$field->name]; $count++; } call_user_func_array("mysqli_stmt_bind_result", $fields); } } ?>
apiBaseClass.php
Ну вот мы подошли к одному из самых важных классов системы - базовый класс для всех API в системе.
mySQLWorker = MySQLiWorker::getInstance($dbName,$dbHost,$dbUser,$dbPassword); } } function __destruct() { if (isset($this->mySQLWorker)){ //Если было установленно соединение с базой, $this->mySQLWorker->closeConnection(); //то закрываем его когда наш класс больше не нужен } } //Создаем дефолтный JSON для ответов function createDefaultJson() { $retObject = json_decode("{}"); return $retObject; } //Заполняем JSON объект по ответу из MySQLiWorker function fillJSON(&$jsonObject, &$stmt, &$mySQLWorker) { $row = array(); $mySQLWorker->stmt_bind_assoc($stmt, $row); while ($stmt->fetch()) { foreach ($row as $key => $value) { $key = strtolower($key); $jsonObject->$key = $value; } break; } return $jsonObject; } } ?>
Как видно данный класс содержит в себе несколько «утилитных» методов, таких как:
конструктор в котором осуществляется соединение с базой, если текущее API собирается работать с базой;
деструктор - следит за освобождением ресурсов - разрыв установленного соединения с базой
createDefaultJson - создает дефолтный JSON для ответа метода
fillJSON - если подразумевается что запрос вернет только одну запись, то данный метод заполнит JSON для ответа данными из первой строки ответа от БД
Создадим свой API
Вот собственно и весь костяк этого API. Теперь рассмотрим как же это все использовать на примере создания первого API под названием apitest. И напишем в нем пару простых функций:
одну без параметров
одну с параметрами и их же она нам и вернет, чтобы было видно, что она их прочитала
одну которая вернет нам бинарные данные
И так создаем класс apitest.php следующего содержания
createDefaultJson(); $retJSON->withoutParams = "It\"s method called without parameters"; return $retJSON; } //http://www.example.com/api/?apitest.helloAPIWithParams={"TestParamOne":"Text of first parameter"} function helloAPIWithParams($apiMethodParams) { $retJSON = $this->createDefaultJson(); if (isset($apiMethodParams->TestParamOne)){ //Все ок параметры верные, их и вернем $retJSON->retParameter=$apiMethodParams->TestParamOne; }else{ $retJSON->errorno= APIConstants::$ERROR_PARAMS; } return $retJSON; } //http://www.example.com/api/?apitest.helloAPIResponseBinary={"responseBinary":1} function helloAPIResponseBinary($apiMethodParams){ header("Content-type: image/png"); echo file_get_contents("http://habrahabr.ru/i/error-404-monster.jpg"); } } ?>
Для удобства тестирования методов, я дописываю к ним адрес по которому я могу сделать быстрый запрос для тестирования.
И так у нас три метода
Function helloAPI() { $retJSON = $this->createDefaultJson(); $retJSON->withoutParams = "It\"s method called without parameters"; return $retJSON; }
Это простой метод без параметров. Его адрес для GET вызова www.example.com/api/?apitest.helloAPI= {}
Результатом выполнения будет вот такая страница (в браузере)
Этот метод принимает в параметры. Обязательным является TestParamOne, для него и сделаем проверку. Его его не передать, то будет выдан JSON с ошибкой
Function helloAPIWithParams($apiMethodParams) {
$retJSON = $this->createDefaultJson();
if (isset($apiMethodParams->TestParamOne)){
//Все ок параметры верные, их и вернем
$retJSON->retParameter=$apiMethodParams->TestParamOne;
}else{
$retJSON->errorno= APIConstants::$ERROR_PARAMS;
}
return $retJSON;
}
Результат выполнения
helloAPIResponseBinary
И последний метод helloAPIResponseBinary - вернет бинарные данные - картинку хабра о несуществующей странице (в качестве примера)
function helloAPIResponseBinary($apiMethodParams){
header("Content-type: image/jpeg");
echo file_get_contents("http://habrahabr.ru/i/error-404-monster.jpg");
}
Как видно - здесь есть подмена заголовка для вывода графического контента.
Результат будет такой
PHP offers three different APIs to connect to MySQL. Below we show the APIs provided by the mysql, mysqli, and PDO extensions. Each code snippet creates a connection to a MySQL server running on "example.com" using the username "user" and the password "password". And a query is run to greet the user.
Example #1 Comparing the three MySQL APIs
// mysqli
$mysqli
= new
mysqli
("example.com"
,
"user"
,
"password"
,
"database"
);
$result
=
$mysqli
->
query
();
$row
=
$result
->
fetch_assoc
();
// PDO
$pdo
= new
PDO
("mysql:host=example.com;dbname=database"
,
"user"
,
"password"
);
$statement
=
$pdo
->
query
("SELECT "Hello, dear MySQL user!" AS _message FROM DUAL"
);
$row
=
$statement
->
fetch
(PDO
::
FETCH_ASSOC
);
echo
htmlentities
($row
[
"_message"
]);
// mysql
$c
=
mysql_connect
("example.com"
,
"user"
,
"password"
);
mysql_select_db
("database"
);
$result
=
mysql_query
("SELECT "Hello, dear MySQL user!" AS _message FROM DUAL"
);
$row
=
mysql_fetch_assoc
($result
);
echo
htmlentities
($row
[
"_message"
]);
?>
Recommended API
It is recommended to use either the mysqli or PDO_MySQL extensions. It is not recommended to use the old mysql extension for new development, as it was deprecated in PHP 5.5.0 and was removed in PHP 7. A detailed feature comparison matrix is provided below. The overall performance of all three extensions is considered to be about the same. Although the performance of the extension contributes only a fraction of the total run time of a PHP web request. Often, the impact is as low as 0.1%.
Feature comparison
| ext/mysqli | PDO_MySQL | ext/mysql | |
|---|---|---|---|
| PHP version introduced | 5.0 | 5.1 | 2.0 |
| Included with PHP 5.x | Yes | Yes | Yes |
| Included with PHP 7.x | Yes | Yes | No |
| Development status | Active | Active | Maintenance only in 5.x; removed in 7.x |
| Lifecycle | Active | Active | Deprecated in 5.x; removed in 7.x |
| Recommended for new projects | Yes | Yes | No |
| OOP Interface | Yes | Yes | No |
| Procedural Interface | Yes | No | Yes |
| API supports non-blocking, asynchronous queries with mysqlnd | Yes | No | No |
| Persistent Connections | Yes | Yes | Yes |
| API supports Charsets | Yes | Yes | Yes |
| API supports server-side Prepared Statements | Yes | Yes | No |
| API supports client-side Prepared Statements | No | Yes | No |
| API supports Stored Procedures | Yes | Yes | No |
| API supports Multiple Statements | Yes | Most | No |
| API supports Transactions | Yes | Yes | No |
| Transactions can be controlled with SQL | Yes | Yes | Yes |
| Supports all MySQL 5.1+ functionality | Yes | Most | No |
Похожие статьи
