Versioning
The version is in the path. v1 is current, unversioned URLs still answer, and what changes without a version bump.
The version is in the path
Every data endpoint on gateway.apinoa.com lives under a version segment. v1 is the current
version, and the one a new integration should use:
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" \
-H "x-api-key: YOUR_API_KEY"Unversioned URLs still work
The old https://gateway.apinoa.com/{marketplace}/{op} form keeps answering, with the same body it
always returned. It is deprecated, not removed: every response carries
| Header | Value |
|---|---|
Deprecation | true |
Sunset | Tue, 20 Oct 2026 00:00:00 GMT |
Link | <https://gateway.apinoa.com/v1/…>; rel="successor-version" |
Link names the exact URL that replaces the one you called, so a client can find its own way forward.
After 20 October 2026 the unversioned paths may stop answering. Move before then.
What we may change inside v1
- We add. New fields on a response, new optional parameters, new marketplaces and new operations
arrive in
v1without a version bump. Parse leniently and ignore what you don't recognise. - We do not break. Removing a field, renaming one, changing its type or its units, or making an
optional parameter required would be a new version with its own path segment — never an edit to
v1.
An absent field has always meant "the marketplace did not say", and still does. It is not a change.
What v1 renamed
Three AliExpress endpoints belong to that marketplace's own dialect, which predates the normalized
schema. They have no v1 URL — under /v1 they return 404 NOT_IN_V1 with a Link to the
successor:
| Deprecated | v1 |
|---|---|
/aliexpress/keyword-search | /v1/aliexpress/search |
/aliexpress/product-details | /v1/aliexpress/product |
/aliexpress/visual-search and /aliexpress/image-search | /v1/aliexpress/image-search |
image-search is the one to read twice. The segment is the same on both sides, the body is not.
Unversioned /aliexpress/image-search returns AliExpress's own legacy shape; /v1/aliexpress/image-search
returns the normalized SearchResult that every other marketplace returns. Adding /v1 to that URL
changes the response, so port the parsing with it.
/aliexpress/visual-search was only ever the normalized visual search wearing a second-choice name,
because the dialect had taken image-search. Inside v1 the dialect is not present, so the canonical
name is free and the override is gone.
Everything else is a straight prefix: /walmart/search becomes /v1/walmart/search, and nothing about
the request or the response changes.