imbajin commented on PR #3029:
URL: https://github.com/apache/hugegraph/pull/3029#issuecomment-4469401313
A larger concern is that this PR changes the public REST API response
contract. The server / pd / store REST APIs may already be consumed by external
services, so a large response-format change can have significant downstream
impact.
Current response shapes include fields such as:
```text
server errors:
exception / message / cause / trace
pd responses:
message / data / status
or status / error
store errors:
module-specific business error codes
```
The new envelope introduces a different shape:
```text
ApiResponse:
code / message / data / status
```
That can break clients that parse existing fields like `exception`, `error`,
`status`, or store-specific business codes. Even if the new format is cleaner,
this kind of API contract change should be designed and discussed carefully
before implementation.
I think we should first decide the compatibility and migration strategy, for
example:
```text
Questions to settle before implementation:
- Is this intended to be a breaking public API response change?
- If not, how do old clients keep receiving the old format?
- Should the unified format be opt-in through a version/header/parameter?
- Is there a deprecation period with compatibility fields?
- Should normal responses also be wrapped, or only error responses?
- Is `code` the HTTP status or the business error code?
- What should be documented in REST docs / OpenAPI / release notes?
```
If this is intended to be a breaking change, it should probably go through
community discussion and come with docs, migration notes, OpenAPI updates, and
REST-level compatibility tests. If it is not intended to be breaking, then the
implementation needs an explicit compatibility layer rather than replacing
existing response bodies directly.
In short:
```text
First:
define API contract + compatibility/migration plan
Then:
implement the unified response format against that contract
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
