{"id":21894396,"url":"https://github.com/pocket/firefox-api-proxy","last_synced_at":"2026-02-17T03:11:43.006Z","repository":{"id":167012386,"uuid":"560556269","full_name":"Pocket/firefox-api-proxy","owner":"Pocket","description":"This is FirefoxAPIProxy","archived":false,"fork":false,"pushed_at":"2025-03-31T17:41:41.000Z","size":1091,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-06-06T20:13:31.450Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Pocket.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-11-01T18:56:15.000Z","updated_at":"2025-02-07T06:46:27.000Z","dependencies_parsed_at":"2023-09-25T00:17:23.183Z","dependency_job_id":"5b29e4e0-2061-4aec-a889-84664c4f497f","html_url":"https://github.com/Pocket/firefox-api-proxy","commit_stats":null,"previous_names":["pocket/firefox-api-proxy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Pocket/firefox-api-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pocket%2Ffirefox-api-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pocket%2Ffirefox-api-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pocket%2Ffirefox-api-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pocket%2Ffirefox-api-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Pocket","download_url":"https://codeload.github.com/Pocket/firefox-api-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pocket%2Ffirefox-api-proxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265324585,"owners_count":23747106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-28T13:22:24.651Z","updated_at":"2026-02-17T03:11:42.969Z","avatar_url":"https://github.com/Pocket.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Firefox API Proxy\n\nThis service proxies Firefox browser API requests across multiple back end services.\n\nThis service is only intended to be used by firefox clients. It has a lot of convention and rigidity that is specifically tailored to that client.\n\n## What's different about Firefox?\n\nFirefox is released through a lengthy release process. It takes a long time for code to reach users, and it takes a long time for users to stop using code.\n\n\u003chttps://whattrainisitnow.com/calendar/\u003e Provides dates when specific releases will reach end users.\n\n\u003chttps://endoflife.date/firefox\u003e Provides dates when specific versions will reach support end of life (but not necessarily when users will stop using it!)\n\nThe bookkeeping we have for other services can be lacking here, because the date code is committed can be so far from when it actually reaches end users, and the code in firefox never really leaves production use.\n\nThe [OpenAPI Spec](./openapi.yml) in this repo codifies the contract this service has with firefox in a single place, and documents the at least first and last versions of firefox stable to consume each API path. This documentation bridges the gap between agile and waterfall processes, and allows us to make confident decisions around API support requirements and deprecation without digging into multiple commits in multiple code bases.\n\nTypes are also generated from this API spec, ensuring that internal GraphQL client changes are compatible with the API spec and contract.\n\n## Application Overview\n\n[Express](https://expressjs.com) is being used to receive requests.\n\n[OpenAPI](https://swagger.io/specification/) is being used for documentation, request validation, response validation, and will be leveraged in the future for additional protections against breaking changes.\n\nThis initial implementation transforms requests against this proxy, into requests against the 'pocket-graph' via the Web graphql proxy, providing a subset of the V3 Web API's functionality specifically for firefox clients (desktop, and probably mobile in the future).\n\n## File structure\n\n- the infrastructure code is present in `.aws`\n- the application code is in `src`\n- `.circleci` contains circleCI setup\n- `openapi.yml` contains api documentation\n\n## Develop Locally\n\n### First time setup\n\nClone the repo:\n\n```bash\ngit clone git@github.com:Pocket/firefox-api-proxy.git\ncd firefox-api-proxy\n```\n\n### Running tests\n\n```bash\nnpm run test\n```\n\n### Testing locally\n\nStart the server with:\n\n```bash\nnpm ci\nnpm run start:dev\n```\n\nYou will need authentication appropriate for the web V3 API deployment environment that is backing requests.\n\n### E2E local testing with curl\n\nLocal E2E testing requires production Session Auth (cookie) authentication.\n\nA helper script for generating authentication curl args can be found at [./scripts/scrapeCookie.js](./scripts/scrapeCookie.js).\n\nCurl sample:\n\n```bash\n`curl 'http://localhost:4028/desktop/v1/recent-saves?count=1' \u003cAUTH HEADERS GO HERE\u003e`\n```\n\n### Leading with documentation, generated types\n\nIt is strongly suggested to lead implementation of features with changes to:\n\n- `./openapi.yml`\n- `./src/graphql-proxy/**/*.graphql`\n\nThese files are used to generate the types files in `./src/generated/*` with the following npm script:\n\n```bash\nnpm run codegen\n```\n\nUpon changing these files and generating types, the compiler and unit tests should guide you through required changes to remain compatible with older versions of the APIs.\n\n## About errors in this service\n\nAll errors contain an `id`. These are just random strings that you can\nsearch for in this repo to get more context on an error.\n\nThis service needs to provide an API for **every** version of Firefox that\never gets deployed against this service. When a client receives a 5XX\nerror response, follow these guidelines:\n\n- 500 Error\n  - This service itself can have bugs, or may not be equipped to handle every error that can result from utilizing dependencies. In these cases, this service needs to protect itself and will redact errors. If you see one of these errors, please open a bug against this service.\n- 502 Error\n  - This service is equipped to handle the currently known GraphQL errors associated with its queries. When these errors are encountered, this service will forward the GraphQL error to Firefox for informational purposes, **however do not handle GraphQL errors directly in Firefox**. The graph internals may change without notice, and the names in error messages may also change without notice in turn. In this case, do one of the following:\n    1. If the error includes all of the details needed to handle it, implement a new error handler in this service that transforms the error into an appropriate 4XX error. Add it to `defaultHandlers` in [GraphQLErrorHandler](./src/api/error/graphQLErrorHandler.ts) if it is an error all routes must handle. Otherwise, add it to a route specific error handler if not.\n    2. If the error is too vague to handle it in this service, open a bug against the appropriate GraphQL server component. `#support-backend` can help identify the appropriate component if needed.\n\nAll 5XX errors get recorded as events in sentry, and logged into\ncloudwatch with correlating tags between the two.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpocket%2Ffirefox-api-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpocket%2Ffirefox-api-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpocket%2Ffirefox-api-proxy/lists"}