Open issues

Known bugs and limitations of the current version of REST Bundle (1.3, not released yet; the latest release is 1.2.0): symptom, cause and workaround. Fixed ones are on the Fixed issues page.

Validation errors return 400, not 422

Symptom. A #[RPC\Assertions] violation or a wrong parameter type gives 400 with RestBadRequestException, although the error table maps ConstraintsImposedException → 422.

Cause. The RPC core returns the error as an RPC error with code -32602; the REST layer recreates an RpcBadParamException from it, not a ConstraintsImposedException. Only a ConstraintsImposedException that reaches the REST layer directly gets 422.

Workaround. Expect 400 with per-parameter messages in detail-data.

Enum parameters are not converted from a string

Symptom. GET /rest/items?status=active for a Status $status parameter (backed enum) returns 400 with a type error.

Cause. Query, path and form values are strings; RpcFromRest::castString() casts only scalar types, and the RPC core does not convert a string to an enum, equally for REST and JSON-RPC.

Workaround. Accept a string and convert the value in the method (Status::from($status)).

GET method parameters are documented as a request body

Symptom. In OpenAPI a GET operation has a requestBody with the method parameters, and the Postman collection request has a raw JSON body. Client generators and Postman send the parameters in the body of a GET request instead of the query string.

Cause. OpenApiAdapter::buildParam() and PostmanAdapter::buildService() put all parameters except path variables into the body regardless of the HTTP method.

Workaround. The bundle accepts parameters from the query string (see Request parameters); for GET methods pass them in the query manually.

Only the first HTTP method of a route is documented

Symptom. A method with #[Route(..., methods: ['GET', 'POST'])] accepts both HTTP methods, but OpenAPI and Postman contain only the GET operation.

Cause. OpenApiAdapter::buildService() takes current($route->getMethods()), PostmanAdapter::buildService() takes $route->getMethods()[0]. Found in the code.

Workaround. Publish the method with a single HTTP method.

REST documentation is not cached

Symptom. Every GET /rest, GET /rest/postman request builds the document again; there is no ETag and 304 Not Modified as in the RPC documentation.

Cause. RestEntryPointController::openapiAction() / postmanAction() call the adapter every time; JsonRpcBundle documentation caching works only for RPC routes.

Workaround. Cache the response at the HTTP cache or web server level, or do not expose the documentation in production.