docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/rest-bundle/installation.md
new file +110
ā0
1
+
# Installing REST Bundle
2
+
3
+
:::info
4
+
Requirements: PHP ^8.4, Symfony ^7.2 or ^8.0, `cebe/php-openapi` ^1.8 and `ufo-tech/json-rpc-bundle`: ^10.2.3 for 1.2, ^10.4.2 for 1.3 (not released yet).
5
+
:::
6
+
7
+
The application must already run [JsonRpcBundle](/docs/api/json-rpc-bundle/installation): REST Bundle uses its method map, the `ufo_json_rpc` settings, security and translations.
8
+
9
+
## Step 0: composer.json setup
10
+
11
+
For Symfony Flex to register the bundle and create the routes file automatically, add the UFO-Tech recipes repository to your `composer.json` (the same as for [JsonRpcBundle](/docs/api/json-rpc-bundle/installation)):
12
+
13
+
```json
14
+
{
15
+
"extra" : {
16
+
"symfony": {
17
+
"endpoint": [
18
+
"https://api.github.com/repos/ufo-tech/recipes/contents/index.json?ref=main",
19
+
"flex://defaults"
20
+
]
21
+
}
22
+
}
23
+
}
24
+
```
25
+
26
+
## Step 1: Installation
27
+
28
+
```bash
29
+
composer require ufo-tech/rest-bundle
30
+
```
31
+
32
+
## Step 2: Registering the package
33
+
34
+
Make sure the bundle is registered in `config/bundles.php` after JsonRpcBundle:
35
+
36
+
```php
37
+
return [
38
+
// ...
39
+
Ufo\JsonRpcBundle\UfoJsonRpcBundle::class => ['all' => true],
40
+
Ufo\RestBundle\RestBundleBundle::class => ['all' => true],
41
+
];
42
+
```
43
+
44
+
## Step 3: Registering routes
45
+
46
+
:::warning
47
+
If you completed **"Step 0"**, the file was created automatically and you can skip this step.
48
+
:::
49
+
50
+
Add the file `config/routes/ufo_rest_api.yaml` (the template is in the package: `install/routes/ufo_rest_api.yaml`):
51
+
52
+
```yaml
53
+
# config/routes/ufo_rest_api.yaml
54
+
ufo_rest_api:
55
+
resource: ../../vendor/ufo-tech/rest-bundle/config/router.yaml
56
+
prefix: /rest
57
+
trailing_slash_on_root: false
58
+
```
59
+
60
+
`prefix` is the address of the REST entry point. Separate entry points for [API groups](/docs/api/json-rpc-bundle/functionality/groups) are described in [Routing](/docs/api/rest-bundle/routing).
61
+
62
+
The bundle has no configuration file of its own; see [Configuration](/docs/api/rest-bundle/config).
63
+
64
+
## Step 4: The first REST method
65
+
66
+
Add the Symfony `#[Route]` attribute to a method of an existing RPC procedure:
67
+
68
+
```php
69
+
use Symfony\Component\Routing\Attribute\Route;
70
+
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
71
+
use Ufo\RpcObject\RPC;
72
+
73
+
#[RPC\Info('catalog')]
74
+
#[Route('/catalog', name: 'catalog')]
75
+
class CatalogApi implements IRpcService
76
+
{
77
+
#[Route('/items', name: 'list', methods: ['GET'])]
78
+
public function list(int $page = 1): array
79
+
{
80
+
return ['page' => $page, 'items' => []];
81
+
}
82
+
}
83
+
```
84
+
85
+
## Verification
86
+
87
+
| Request | What it returns |
88
+
| --- | --- |
89
+
| `GET /rest` | An OpenAPI 3.1 document |
90
+
| `GET /rest/postman` | A Postman collection |
91
+
| `GET /rest/catalog/items?page=2` | The result of `catalog.list` |
92
+
93
+
```bash
94
+
curl 'https://example.com/rest/catalog/items?page=2' \
95
+
-H 'Ufo-RPC-Token: change-me'
96
+
```
97
+
98
+
```json
99
+
{"page": 2, "items": []}
100
+
```
101
+
102
+
Casting `"2"` from the query to `int` appeared in 1.3; in 1.2 this request returns `400` (see [Request parameters](/docs/api/rest-bundle/requests)).
103
+
104
+
A token is required if `protected_api: true` is set in the JsonRpcBundle settings (the default). `bin/console debug:router | grep ufo_rest` shows the names of the generated routes.
105
+
106
+
## What next?
107
+
108
+
* [Routing](/docs/api/rest-bundle/routing): path and name rules, versions, API groups.
109
+
* [Request parameters](/docs/api/rest-bundle/requests): where method parameters come from.
110
+
* [Security](/docs/api/rest-bundle/security): tokens for calls and documentation.