docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/installation.md
new file +153
ā0
1
+
# Installing JsonRpcBundle
2
+
3
+
:::info
4
+
Requirements for version 10.x: PHP >= 8.4, Symfony ^7.2 or ^8.0, the `ext-dom` and `ext-sysvsem` extensions.
5
+
:::
6
+
7
+
## Step 0: composer.json configuration
8
+
9
+
For Symfony Flex to apply all the configuration automatically when the package is installed, add the UFO-Tech recipes repository to your `composer.json`:
10
+
11
+
```json
12
+
{
13
+
"extra" : {
14
+
"symfony": {
15
+
"endpoint": [
16
+
"https://api.github.com/repos/ufo-tech/recipes/contents/index.json?ref=main",
17
+
"flex://defaults"
18
+
]
19
+
}
20
+
}
21
+
}
22
+
```
23
+
24
+
:::info
25
+
For details on private Symfony Flex recipes, see the [Symfony documentation](https://symfony.com/doc/current/setup/flex_private_recipes.html).
26
+
:::
27
+
28
+
## Step 1: Installation
29
+
30
+
In the project directory, run the command to download the latest version of the package:
31
+
32
+
```bash
33
+
composer require ufo-tech/json-rpc-bundle
34
+
```
35
+
36
+
## Step 2: Registering the package
37
+
38
+
Make sure the package is registered in `config/bundles.php`:
39
+
40
+
```php
41
+
return [
42
+
// ...
43
+
Ufo\JsonRpcBundle\UfoJsonRpcBundle::class => ['all' => true],
44
+
// ...
45
+
];
46
+
```
47
+
48
+
## Step 3: Configuration
49
+
50
+
:::warning
51
+
If you completed **"Step 0"**, the file was created automatically and you can skip this step.
52
+
:::
53
+
54
+
Add the `config/packages/ufo_json_rpc.yaml` file with a minimal configuration:
55
+
56
+
```yaml
57
+
# config/packages/ufo_json_rpc.yaml
58
+
ufo_json_rpc:
59
+
security:
60
+
protected_api: true # check the token for RPC requests
61
+
protected_doc: false # documentation is open
62
+
token_name: 'Ufo-RPC-Token' # name of the header with the token
63
+
clients_tokens:
64
+
- '%env(resolve:UFO_API_TOKEN)%'
65
+
66
+
docs:
67
+
project_name: 'My Project'
68
+
```
69
+
70
+
and the token in `.env.local`:
71
+
72
+
```dotenv
73
+
UFO_API_TOKEN=change-me
74
+
```
75
+
76
+
All parameters are described in the [Bundle configuration](/docs/api/json-rpc-bundle/config) section.
77
+
78
+
## Step 4: Registering routes
79
+
80
+
:::warning
81
+
If you completed **"Step 0"**, the file was created automatically and you can skip this step.
82
+
:::
83
+
84
+
Add the `config/routes/ufo_json_rpc.yaml` file:
85
+
86
+
```yaml
87
+
# config/routes/ufo_json_rpc.yaml
88
+
ufo_json_rpc:
89
+
resource: ../../vendor/ufo-tech/json-rpc-bundle/config/router.yaml
90
+
prefix: /rpc
91
+
trailing_slash_on_root: false
92
+
```
93
+
94
+
The API will be available at `https://example.com/rpc`. To change the path, change `prefix`.
95
+
96
+
:::info
97
+
Before version 10, the installation recipe used the `/api` prefix. Existing route files are not changed on upgrade, so old projects keep working at the previous address.
98
+
:::
99
+
100
+
One application can have several entry points with different sets of methods; see [API groups](/docs/api/json-rpc-bundle/functionality/groups).
101
+
102
+
## Step 5: Profit
103
+
104
+
:::success subtitle="Congratulations!!!"
105
+
Your RPC server is ready to go!!!
106
+
:::
107
+
108
+
## Verification
109
+
110
+
> Does it really work? (c)
111
+
112
+
| Request | What it returns |
113
+
| --- | --- |
114
+
| `GET /rpc` | [OpenRPC](https://spec.open-rpc.org/) document with all methods |
115
+
| `GET /rpc?info` | Only the document header (info, servers), without methods |
116
+
| `GET /rpc/postman` | Postman collection |
117
+
| `POST /rpc` | Executes a JSON-RPC request |
118
+
119
+
The `ping` method is installed right away, so you can send a `POST` request:
120
+
121
+
::::columns
122
+
:::col
123
+
**Request**:
124
+
```bash
125
+
curl -X POST https://example.com/rpc \
126
+
-H 'Content-Type: application/json' \
127
+
-H 'Ufo-RPC-Token: change-me' \
128
+
-d '{"jsonrpc": "2.0", "id": 1, "method": "ping"}'
129
+
```
130
+
:::
131
+
132
+
:::col
133
+
**Response**:
134
+
```json
135
+
{
136
+
"jsonrpc": "2.0",
137
+
"id": 1,
138
+
"result": "PONG"
139
+
}
140
+
```
141
+
:::
142
+
::::
143
+
144
+
The same from the console:
145
+
146
+
```bash
147
+
php bin/console ufo:rpc:process '{"jsonrpc": "2.0", "id": 1, "method": "ping"}' --ufo-rpc-token=change-me
148
+
```
149
+
150
+
## What's next?
151
+
152
+
* Adjust the [configuration](/docs/api/json-rpc-bundle/config) to your needs.
153
+
* Add [custom methods](/docs/api/json-rpc-bundle/add_rpc_service).