Власні API методи
В JsonRpcBundle версії 7 конфігурація зазнала суттєвих змін і не має зворотної сумісності з більш ранніми версіями.
Ви можете легко додавати власні API методи до RPC сервера.
Для цього вам достатньо в будь-якому місці вашого додатку зробити будь-який клас який має стати API Сервісом, цей клас має реалізувати інтерфейс Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService. Цей інтерфейс не навʼязує класу жодної логіки, він необхідний лише для того, щоб Symfony зрозумів, що має його сприймати як сервіс, що доступний для RPC сервера.
Реалізуйте в вашому класі будь-який публічний метод і він автоматично буде доступний як API Сервіс.
Після виконання попередніх вказівок у вас вже будуть доступні нові методи в API. За замовченням назви методів складаються з <className>.<methodName>.
Іменування класів
В разі потреби, ви можете створити кілька класів, що будуть доступні як API Сервіси.
Враховуючи їх неймінги <className>.<methodName>, рекомендую підходити до вибору назви методу як до простої вказівки що він робить, а до назви класу як до неймспейсу API методу.
Гарна практика
Класс Messenger містить методи sendEmail(),sendSms(),класс CartResolverмістить методи addProduct(),getProducts(), calculateDiscount()
в API будуть доступні методи
- CartResolver.addProduct
- CartResolver.getProducts
- CartResolver.calculateDiscount
- Messenger.sendEmail
- Messenger.sendSms
Навіть просто поглянувши на назви методів зрозуміло що може робити ваш сервер.
Такий підхід надає можливість використовувати одноіменні методи в різних класах:
- ProductService.create
- ProductService.getName
- UserService.create
- UserService.getName
Простий старт
Наступний приклад має продемонструвати легкість додавання ваших методів до API.
Код
<?php
namespace App\Api\Procedures;
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
class ExampleApi implements IRpcService
{
public function __construct(
// connecting some dependencies to retrieve data
) {}
public function getUserNameByUuid(
string $userId
): string
{
// some logic get user info by id
return 'some result';
}
public function sendEmail(
string $email,
string $text,
string $subject = 'Message without subject'
): bool
{
// some logic send email
return true;
}
}
Праворуч приклад документації, що сервер згенерує по цьому класу.
Основна інформація щодо назв параметрів, їх типів та опціональності отримується завдяки ReflectionClass, важливим є порядок аргументів методу, їх typehint.
Документація
{
"methods": {
"ExampleApi.getUserNameByUuid": {
"name": "ExampleApi.getUserNameByUuid",
"description": "",
"parameters": {
"userId": {
"type": "string",
"name": "userId",
"description": "",
"optional": false
}
},
"returns": "string",
"responseFormat": "string"
},
"ExampleApi.sendEmail": {
"name": "ExampleApi.sendEmail",
"description": "",
"parameters": {
"email": {
"type": "string",
"name": "email",
"description": "",
"optional": false
},
"text": {
"type": "string",
"name": "text",
"description": "",
"optional": false
},
"subject": {
"type": "string",
"name": "subject",
"description": "",
"optional": true,
"default": "Message without subject"
}
},
"returns": "boolean",
"responseFormat": "boolean"
}
}
}
Тепер можемо зробити POST запити на обидва нових метода API і подивитися на результат.
POST запити
Request
{
"id": "example_request",
"method": "ExampleApi.getUserNameByUuid",
"params": {
"userId": "1111"
}
}
Response
{
"id": "example_request",
"result": "some result",
"jsonrpc": "2.0"
}
Request
{
"id": "example_request",
"method": "ExampleApi.sendEmail",
"params": {
"email": "user@example.com",
"subject": "This is test mail",
"text": "Hi! This is test send mail by API"
}
}
Response
{
"id": "example_request",
"result": true,
"jsonrpc": "2.0"
}
Для спрощення сприйняття документації, всі подальші приклади буду надавати на одному методі sendEmail
Опис методів та параметрів
Документатор спирається на всі наявні дані, що належать методу та його аргументам (назви, типи вхідних і вихідних даних, докблоки). Тож, опис методів і параметрів можна збагатити за рахунок докблоків.
Додамо опис методу і параметрів.
Код
<?php
// ...
/**
* A method for sending an email message
* @param string $email The email address
* @param string $text Message body
* @param string $subject Optional message subject parameter
* @return bool
*/
public function sendEmail(
string $email,
string $text,
string $subject = 'Message without subject'
): bool
{
// some logic send email
return true;
}
// ...
Зверніть увагу на документацію, тепер в ній відображається додаткова інформація про метод і його параметри.
Документація
{
"methods": {
"ExampleApi.sendEmail": {
"name": "ExampleApi.sendEmail",
"description": "A method for sending an email message",
"parameters": {
"email": {
"type": "string",
"name": "email",
"description": "The email address",
"optional": false
},
"text": {
"type": "string",
"name": "text",
"description": "Message body",
"optional": false
},
"subject": {
"type": "string",
"name": "subject",
"description": "Optional message subject parameter",
"optional": true,
"default": "Message without subject"
}
},
"returns": "boolean",
"responseFormat": "boolean"
}
}
}
RPC attributes
Для більш гнучкого налаштування ваших методів API JsonRpcBundle використовує такий інструмент як php атрибути.
За допомогою спеціалізованих атрибутів ви можете:
- налаштувати псевдоніми для методів;
- вказати формат відповіді для методів (якщо відповідь у вигляді масива, обʼєкта або колекції обʼєктів);
- налаштувати валідацію вхідних параметрів;
- налаштувати кешування відповідей.
Докладніше про ці атрибути в підрозділах документації.