Polaris management API spec improvements
- Dominant language
- Java
- Stars
- 2.1k
- Forks
- 522
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 137
Description
### Describe the bug
The current Polaris management spec has a few shortcomings:
* It exposes and requires persistence internals (#556) like entityVersion, created/modified timestamps
* It exposes the rather internal persistence model via a public API
* None of the list requests/responses are use paging
* It uses the generic property bags, which requires detailed knowledge of the properties on each client (#555)
* Create/update/delete requests rely on persistence internals and changes are improperly validated on the server side
I propose a complete overhaul of that API, as a v2 and eventually remove v1 before 1.0:
* Enable pagination of list requests using opaque paging-tokens
* Have a data model built on actual, distinct properties instead of generic property bags. This helps users to reason about individual properties and also helps to not accidentally exposing sensitive information.
* Have specific update requests (or update request payloads) for each kind of change instead of sending the whole entity and update everything. This is much easier to reason about from the client side and also much easier to verify & validate on the server side.
### To Reproduce
_No response_
### Actual Behavior
_No response_
### Expected Behavior
_No response_
### Additional context
_No response_
### System information
_No response_
Contributor guide
Research direction
No files, tests, or entry points are named. Start by reviewing the existing Polaris management API and the referenced issues #555 and #556, then define the v2 scope around opaque pagination tokens, distinct properties, and specific update requests. Done requires an agreed, implementable API design and a migration or removal plan for v1.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100