Додавання процедур

Версія 3.9 додана 2024/05/10 10:10 автором Ashterix
Зміст

Ви можете легко додавати власні 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.

Код

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<?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. 

Документація

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
   "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
1
2
3
4
5
6
7
{
   "id": "example_request",
   "method": "ExampleApi.getUserNameByUuid",
   "params": {
       "userId": "1111"
    }
}
Response
1
2
3
4
5
{
   "id": "example_request",
   "result": "some result",
   "jsonrpc": "2.0"
}

 

Request
1
2
3
4
5
6
7
8
9
{
   "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
1
2
3
4
5
{
   "id": "example_request",
   "result": true,
   "jsonrpc": "2.0"
}

Опис методів та параметрів

Документатор спирається на всі наявні дані, що належать методу та його аргументам (назви, типи вхідних і вихідних даних, докблоки). Тож, опис методів і параметрів можна збагатити за рахунок докблоків.

Додамо опис методу і параметрів.