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

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