microsoft / microsoft/planetary-computer-apis

Avoid $ref in /queryables

Open
#153 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
129
Forks
33
Avg merge
2d 20h
Merged PRs (30d)
1

Description

Neither a bug nor really a feature, so opening a blank issue.

The /queryables endpoints refer to external schemas using $ref. This leads to a lot of downstream HTTP requests in clients, e.g. STAC Browser. For example requesting https://planetarycomputer.microsoft.com/api/stac/v1/queryables has a single field defined, which pretty much just refers to a very simple JSON Schema of like 30 bytes: { "type": "string", "minLength": 1 }. For this simple schema. the client has to sends 8(!) http requests returning a total of nearly 10.000 bytes. Could this be improved?

Two alternative solutions could be considered:

  1. Inline at least the simple schemas.
  2. Bundle the schema on the server-side and return the bundled schema.

I'd prefer version 2 as it just is much more lightweight on the clients, which don't need to carry a full $ref parser library. $refs itself are also pretty ill-defined with a lot of different implementation, so the interoperability is pretty bad. The JSON Schema community is currently discussing this, but that will take more time: https://github.com/json-schema-org/referencing https://phil.tech/2022/bundling-openapi-with-javascript/

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the /queryables endpoints and how their JSON Schemas are generated and served. Compare the proposed bundling and inlining approaches, then verify that the response avoids unnecessary external $ref requests while preserving the queryables schema.

Written by the indexing model from the issue text.

Assessment

Tech stack
json, python
Domain
api
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.