What we intend to change. No dates are committed: this is direction, and the changelog is the record of what actually shipped. Every near-term item was found by linting our own published contract or by testing the live API, and the evidence is given so the list can be checked rather than taken on trust.
near_term
id
document-failure-responses
item
Document a failure response on the four operations that have none: GET /ios/info/countries, /ios/info/languages, /play/info/countries and /play/info/languages.
evidence
appstorespy-operation-error-response, 4 errors against the live contract. They take no parameters, so FastAPI emits no 422 and nothing else was declared.
breaking
no
id
declare-tags
item
Declare all five surface tags in the contract's global tags array.
evidence
spectral:oas operation-tag-defined, 5 warnings. Jobs, Events, Suggestions and Search Filter v.2 are used on operations but only Google Play and App Store are declared.
breaking
no
id
declare-total-count
item
Declare the total-count response header in the contract. List operations already send it; a consumer currently has to be told it exists.
evidence
Sent on every list response, absent from all 37 operation definitions.
breaking
no
id
real-version
item
Publish a version that identifies a release instead of the framework default, and record releases in the changelog.
evidence
info.version is "0.0.1". Flagged by appstorespy-info-version-released, and noted independently in the API Evangelist overlay for this provider.
breaking
no
id
method-not-allowed
item
Return 405 for a method mismatch instead of 404. POST to a GET-only path currently answers "Not Found", which sends an integrator looking for a path that is right in front of them.
evidence
Verified on the live API: POST /v1/play/apps/{id}, HEAD /v1/play/apps and DELETE /v1/play/rankings all return 404. The endpoint-name lookup used for billing only matches on a full method match and the middleware treats no-match as not-found.
breaking
yes
handling
A caller branching on 404 for a wrong method would see 405 instead. Goes through the 90-day notice in the deprecation policy.
id
problem-details
item
Offer RFC 9457 application/problem+json on failure responses, negotiated by Accept so the current shapes keep working for existing callers.
evidence
appstorespy-problem-details, 35 operations. Today there are two vendor shapes: {"detail": "..."} from the application and {"message": "...", "code": n} from the edge, and a consumer handling one does not parse the other.
breaking
no
handling
Additive. problem+json is served only when asked for; the existing shapes remain the default until a major version says otherwise.
id
converge-field-names
item
Accept the windowed aggregate names on the lookup surface as aliases, so downloads_month means the same thing everywhere it is accepted.
evidence
Probed every field name against both surfaces on 2026-09-20. GET /{store}/apps and /{store}/apps/{id} reject downloads_month, downloads_lifetime, downloads_daily, downloads_exact, downloads_mark, revenue_month and revenue_lifetime with {"detail": "Wrong field - <name>"}, while POST /{store}/apps/query accepts them. The same metric is `downloads` on one surface and `downloads_month` on the other.
breaking
no
handling
Additive: names that work today keep working, and names that are currently a 400 start resolving. Documented meanwhile in the vocabulary and in the MCP tool descriptions.
id
converge-language-parameter
item
Accept `language` as an alias for `lang` on /play/suggestions and /play/liveops, where the parameter is spelled differently from every other operation for historical reasons.
evidence
`lang` on those two operations, `language` on the other six that take one.
breaking
no
handling
Additive; `lang` continues to work.
id
document-store-specific-fields
item
Mark the fields that exist on only one store in the contract itself, not only in the vocabulary.
evidence
installs, installs_exact and review_count are accepted on the Google Play lookup surface and rejected on the App Store one. Nothing in the contract says so.
breaking
no
exploring
theme
Machine-readable artifacts
why
The data model is already defined in code; not publishing it as its own artifact means every consumer re-derives it from the OpenAPI.
items
JSON Schema per primary resource, published separately from the contract
A JSON-LD context binding field names to shared semantics
Publishing against OpenAPI 3.2
open_question
Whether a JSON-LD context earns its maintenance for this domain, where no widely adopted vocabulary covers app market data.
theme
Developer ergonomics
why
There is no client library in any language, so every consumer writes HTTP plumbing before writing anything of their own. This is the largest gap for human developers, as opposed to agents.
items
A client library, generated from the contract and maintained with it
A getting-started guide distinct from the endpoint reference
A console or sandbox for trying calls without wiring up a key first
A command-line interface for scripting and exploration
open_question
Which language first. The answer should come from what customers actually integrate from rather than from what is easiest to generate.
theme
Agent surface beyond MCP
why
The MCP server shipped on 2026-09-20 covers an agent calling the API with a key it was given. The items below cover an agent that has to identify itself, retry safely, or rehearse a call.
items
An A2A agent card
Idempotency keys, so a retried call is provably the same call
A dry-run mode for rehearsing a filter and seeing its cost before spending it
OAuth with delegated identity, protected resource metadata and dynamic client registration
open_question
Idempotency and dry-run are ordinarily about writes, and this API is read-only. The version worth building here is about credit spend: a retry that does not double-charge, and a way to see what a query would cost before running it.