apache / apache/polaris

Polaris management API spec improvements

Open
#779 0 comments 0 reactions 0 assignees View on GitHub
bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.