retroachievements / api-js Goto Github PK

RetroAchievements/api-docs#37

Use T3 stack for this. Create a dummy account on RA for a web API key, don't ask users to enter their own. Embed the API key directly into the bundle.

Flow will look like:

• Have users enter a username.
• Display a bunch of stats about masteries, rarest achievement, rarest mastery, and some kind of line charts.
• Be sure URLs are shareable.

Stuff to include:

• Bullet point list of features
• Stickers for codeclimate & coverage
• all-contributors
• Function docs with links to Docusaurus
• Projects using (?)
• Include a "why use it" detailing a migration path from v1 to v2
• Developer setup from POV of someone who doesn't know TypeScript

Consumers need to be able to upgrade from v1 to v2 of the library with as little friction and as good DX as possible.

After chewing on this for a little bit, here is how I think the migration could best work:

/** v1 (today) **/
import { getUserSummary } from "@retroachievements/api"
const userSummary = await getUserSummary(...);

/** v2 (upgrade path) **/
import { getUserSummary, unsafe_getUserSummary } from "@retroachievements/api"

// same name as in v1, but is now reimplemented with the new v2 API
const userSummary = await getUserSummary(...);

// this is deprecated and will be removed after a few months, but still uses the old unsafe functions
// that are shipping with v1 of this library. this is a fallback in case something goes wrong.
// users are required to type "unsafe" so they explicitly know this is a dangerous action.
const legacyUserSummary = await unsafe_getUserSummary(...);

This keeps us from having an AngularJS -> Angular 2 kind of situation. Users will bump their major release of this package from 1.x to 2.x and see no breaking changes, as the exports and their arguments/return types will all remain the same.

Internally, getUserSummary of v2 will make whatever new calls are required to "re-implement" the old getUserSummary() function. From the outside, it will behave exactly the same as v1's getUserSummary(). However, internally it is making the new v2 API calls.

@luchaos

Currently the API is giving 503 errors. However when calling functions in the library such as
const consoleIds = await ra_api.getConsoleIds(authorization);

The code throws an unhelpful error

SyntaxError: Unexpected token < in JSON at position 0 at JSON.parse (<anonymous>) at parseJSONFromBytes (node:internal/deps/undici/undici:6571:19) at successSteps (node:internal/deps/undici/undici:6545:27) at node:internal/deps/undici/undici:1211:60 at node:internal/process/task_queues:140:7 at AsyncResource.runInAsyncScope (node:async_hooks:203:9) at AsyncResource.runMicrotask (node:internal/process/task_queues:137:8) at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

I also believe this doesn't include the HTTP status code. The problem comes in that call doesn't appear to parse the response before running the code through the JSON parser, and thus errors in an unhelpful manner..

I'd be willing to take a crack at writing a fix for this, this weekend if that would be ok, though if there's a suggestion on what you would prefer the API should throw/return/report, that would be appreciated, and which error codes should be handled.

Users should be able to consume this library directly from a CDN.

Continue supporting userName for backwards compatibility, but leave it undocumented and point users towards using username instead.

The following endpoint functions have been temporarily disabled server-side:

• getGameInfoAndUserProgress()
• getUserRecentlyPlayedGames()
• getUserSummary()

There is ongoing work to restore the functionality of these endpoints, and it is currently the top priority of the web team.

A roadmap was posted recently by @luchaos here:

[✅ DONE] Optimization Release 1:
deploy v3

[✅ DONE] Optimization Release 2:
import prepared dumps for data up to february 1st
write/finish all async aggregation tasks (some of it has been prepared) to sync remaining data since february 1st
run sync tasks until all data is up to date in old and new schemas

[✅ DONE] Optimization Release 3:
refactor to double write to old and new schemas
rewrite existing queries to use new schemas/denormalized data
turn off sync tasks

[✅ DONE] Optimization Release 4:
reactivate all APIs
remove double writes
remove legacy schemas and code

Blocker: this will depend on the project no longer being set to private.

Ideally, this repo becomes public when 1.0.0-rc.0 is published to npm.

This would be a breaking change.

RetroAchievements/RAWeb#1493

In order to save on multiple API requests per page, it would be beneficial to return the Achievement BadgeURL property on the Achievement object that is returned from the GameExtended endpoint.

Ideally API_GetGameInfoAndUserProgress would get this as well.

Is there a reason this is not included?

• Document every function and response
• Document how to authenticate
• Deploy to Vercel
• Reach out to the Docusaurus team wrt Algolia search
• Be sure analytics are hooked up (cc @luchaos)

RetroAchievements/RAWeb#2090

RetroAchievements/RAWeb#2122

RetroAchievements/RAWeb#2089

RetroAchievements/RAWeb#2092

functions getGame and getGameExtended does not return the release date

NULL or NaN instead of date