Вікі-код для 3. Власні API методи

Остання зміна 2024/05/16 12:34 автором Ashterix
Показати останніх авторів
1 {{box cssClass="floatinginfobox" title="**Зміст**"}}
2 {{toc/}}
3 {{/box}}
4
5 Ви можете легко додавати власні API методи до RPC сервера.
6
7 Для цього вам достатньо в будь-якому місці вашого додатку зробити будь-який клас який має стати API Сервісом, цей клас має реалізувати інтерфейс {{code language="none"}}Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService{{/code}}. Цей інтерфейс не навʼязує класу жодної логіки, він необхідний лише для того, щоб Symfony зрозумів, що має його сприймати як сервіс, що доступний для RPC сервера.
8
9 Реалізуйте в вашому класі будь-який публічний метод і він автоматично буде доступний як API Сервіс.
10
11 (% id="cke_bm_318406S" style="display:none" %) (%%)Після виконання попередніх вказівок у вас вже будуть доступні нові методи в API. За замовченням назви методів складаються з {{code language="none"}}<className>.<methodName>{{/code}}.
12
13 = Іменування класів =
14
15 В разі потреби, ви можете створити кілька класів, що будуть доступні як API Сервіси. 
16 Враховуючи їх неймінги {{code language="none"}}​<className>.<methodName>{{/code}}​, рекомендую підходити до вибору назви методу як до простої вказівки що він робить, а до назви класу як до неймспейсу API методу.
17
18 (% class="box successmessage" %)
19 (((
20 == **Гарна практика** ==
21
22 Класс **//Messenger//** містить методи **//sendEmail()//**//,** sendSms()**//,// //класс// **CartResolver** //містить методи **//addProduct()//**//,** getProducts()**//, //**calculateDiscount()**//
23
24 в API будуть доступні методи
25
26 * //**CartResolver.addProduct**//
27 * //**CartResolver.getProducts**//
28 * //**CartResolver.calculateDiscount**//
29 * **//Messenger.sendEmail//**
30 * **//Messenger.sendSms//**
31
32 Навіть просто поглянувши на назви методів зрозуміло що може робити ваш сервер.
33
34 Такий підхід надає можливість використовувати одноіменні методи в різних класах:
35
36 * //**ProductService.create**//
37 * //**ProductService.getName**//
38 * //**UserService.create**//
39 * //**UserService.getName**//
40 )))
41
42 = Простий старт =
43
44 Наступний приклад має продемонструвати легкість додавання ваших методів до API.
45
46 (% class="row" %)
47 (((
48 (% class="col-xs-12 col-sm-6" %)
49 (((
50 {{code language="php" layout="LINENUMBERS" title="== Код =="}}
51 <?php
52 namespace App\Api\Procedures;
53
54 use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
55
56 class ExampleApi implements IRpcService
57 {
58 public function __construct(
59   // connecting some dependencies to retrieve data
60    ) {}
61
62 public function getUserNameByUuid(
63         string $userId
64     ): string
65     {
66   // some logic get user info by id
67   return 'some result';
68     }
69
70 public function sendEmail(
71         string $email,
72         string $text,
73         string $subject = 'Message without subject'
74     ): bool
75     {
76   // some logic send email
77   return true;
78     }
79 }
80 {{/code}}
81
82 Праворуч приклад документації, що сервер згенерує по цьому класу.
83
84 Основна інформація щодо назв параметрів, їх типів та опціональності отримується завдяки (% class="box code" %)ReflectionClass(%%), важливим є порядок аргументів методу, їх typehint.
85 )))
86
87 (% class="col-xs-12 col-sm-6" %)
88 (((
89 {{code language="json" layout="LINENUMBERS" title="== Документація =="}}
90 {
91 "methods": {
92 "ExampleApi.getUserNameByUuid": {
93 "name": "ExampleApi.getUserNameByUuid",
94 "description": "",
95 "parameters": {
96 "userId": {
97 "type": "string",
98 "name": "userId",
99 "description": "",
100 "optional": false
101 }
102 },
103 "returns": "string",
104 "responseFormat": "string"
105 },
106 "ExampleApi.sendEmail": {
107 "name": "ExampleApi.sendEmail",
108 "description": "",
109 "parameters": {
110 "email": {
111 "type": "string",
112 "name": "email",
113 "description": "",
114 "optional": false
115 },
116 "text": {
117 "type": "string",
118 "name": "text",
119 "description": "",
120 "optional": false
121 },
122 "subject": {
123 "type": "string",
124 "name": "subject",
125 "description": "",
126 "optional": true,
127 "default": "Message without subject"
128 }
129 },
130 "returns": "boolean",
131 "responseFormat": "boolean"
132 }
133 }
134 }
135 {{/code}}
136 )))
137 )))
138
139 Тепер можемо зробити POST запити на обидва нових метода API і подивитися на результат.
140
141 == **POST запити** ==
142
143 (% class="row" %)
144 (((
145 (% class="col-xs-12 col-sm-6" %)
146 (((
147 {{code language="json" layout="LINENUMBERS" title="Request"}}
148 {
149 "id": "example_request",
150 "method": "ExampleApi.getUserNameByUuid",
151 "params": {
152 "userId": "1111"
153 }
154 }
155 {{/code}}
156 )))
157
158 (% class="col-xs-12 col-sm-6" %)
159 (((
160 {{code language="json" layout="LINENUMBERS" title="Response"}}
161 {
162 "id": "example_request",
163 "result": "some result",
164 "jsonrpc": "2.0"
165 }
166 {{/code}}
167
168
169
170 )))
171 )))
172
173 (% class="row" %)
174 (((
175 (% class="col-xs-12 col-sm-6" %)
176 (((
177 {{code language="json" layout="LINENUMBERS" title="Request"}}
178 {
179 "id": "example_request",
180 "method": "ExampleApi.sendEmail",
181 "params": {
182 "email": "user@example.com",
183 "subject": "This is test mail",
184 "text": "Hi! This is test send mail by API"
185 }
186 }
187 {{/code}}
188 )))
189
190 (% class="col-xs-12 col-sm-6" %)
191 (((
192 {{code language="json" layout="LINENUMBERS" title="Response"}}
193 {
194 "id": "example_request",
195 "result": true,
196 "jsonrpc": "2.0"
197 }
198 {{/code}}
199
200
201
202
203 )))
204 )))
205
206
207 (% class="box warningmessage" %)
208 (((
209 Для спрощення сприйняття документації, всі подальші приклади буду надавати на одному методі (//**sendEmail**//)
210 )))
211
212 = Опис методів та параметрів =
213
214 Документатор спирається на всі наявні дані, що належать методу та його аргументам (назви, типи вхідних і вихідних даних, докблоки). Тож, опис методів і параметрів можна збагатити за рахунок докблоків.
215
216 Додамо опис методу і параметрів.
217
218 (% class="row" %)
219 (((
220 (% class="col-xs-12 col-sm-6" %)
221 (((
222 {{code language="php" layout="LINENUMBERS" title="== Код =="}}
223 <?php
224 // ...
225 /**
226 * A method for sending an email message
227 * @param string $email The email address
228 * @param string $text Message body
229 * @param string $subject Optional message subject parameter
230 * @return bool
231 */
232 public function sendEmail(
233 string $email,
234 string $text,
235 string $subject = 'Message without subject'
236 ): bool
237 {
238 // some logic send email
239 return true;
240 }
241
242 // ...
243 {{/code}}
244
245 Зверніть увагу на документацію, тепер в ній відображається додаткова інформація про метод і його параметри.
246
247
248 )))
249
250 (% class="col-xs-12 col-sm-6" %)
251 (((
252 {{code language="json" layout="LINENUMBERS" title="== Документація =="}}
253 {
254 "methods": {
255 "ExampleApi.sendEmail": {
256 "name": "ExampleApi.sendEmail",
257 "description": "A method for sending an email message",
258 "parameters": {
259 "email": {
260 "type": "string",
261 "name": "email",
262 "description": "The email address",
263 "optional": false
264 },
265 "text": {
266 "type": "string",
267 "name": "text",
268 "description": "Message body",
269 "optional": false
270 },
271 "subject": {
272 "type": "string",
273 "name": "subject",
274 "description": "Optional message subject parameter",
275 "optional": true,
276 "default": "Message without subject"
277 }
278 },
279 "returns": "boolean",
280 "responseFormat": "boolean"
281 }
282 }
283 }
284 {{/code}}
285 )))
286 )))
287
288 = RPC attributes =
289
290 Для більш гнучкого налаштування ваших методів API JsonRpcBundle використовує такий інструмент як [[php атрибути>>url:https://www.php.net/manual/en/language.attributes.overview.php]].
291
292 За допомогою спеціалізованих атрибутів ви можете:
293
294 * налаштувати псевдоніми для методів;
295 * вказати формат відповіді для методів (якщо відповідь у вигляді масива, обʼєкта або колекції обʼєктів);
296 * налаштувати валідацію вхідних параметрів;
297 * налаштувати кешування відповідей.
298
299 Докладніше про ці атрибути:
300
301 {{children/}}