apache / apache/pinot

APIs (like /instances) are inconsistently structured or hard to use

Open
#6,018 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
6.1k
Forks
1.5k
Avg merge
1d 21h
Merged PRs (30d)
189

Description

Many APIs do not have consistent or easy to use resource structures. For example, `GET /instances/{instanceName}` may return data like
```
{
"instanceName": "Broker_mybrokerhostname_8099",
"hostName": "Broker_mybrokerhostname",
"enabled": false,
"port": "8099",
"tags": [
"DefaultTenant_BROKER"
],
"pools": null
}
```

Meanwhile `PUT /instances/{instanceName}` requires `host` (not `hostname`) and a `type` field (`BROKER`, `SERVER`, `CONTROLLER`).

Mismatched resources like this make the APIs complex to work with and even harder to use by hand.

Additionally, APIs like `PUT /instances/{instanceName}/updateTags` would be great ot use for upserting empty tags, but that does not appear possible since the Swagger UI reports `tags` is required.

Contributor guide

Open the contributing guide

Research direction

Start by comparing the GET and PUT /instances/{instanceName} payloads and the PUT /instances/{instanceName}/updateTags schema in the Swagger UI. Trace where these API contracts are defined, then align the resource fields and determine how empty tags should be accepted; done means the documented request and response structures are consistent and usable.

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.