Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pocket/firefox-api-proxy

This is FirefoxAPIProxy
https://github.com/pocket/firefox-api-proxy

Last synced: about 1 month ago
JSON representation

This is FirefoxAPIProxy

Awesome Lists containing this project

README 

        
# Firefox API Proxy



This service proxies Firefox browser API requests across multiple back end services.



This 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.



## What's different about Firefox?



Firefox 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.



 Provides dates when specific releases will reach end users.



 Provides dates when specific versions will reach support end of life (but not necessarily when users will stop using it!)



The 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.



The [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.



Types are also generated from this API spec, ensuring that internal GraphQL client changes are compatible with the API spec and contract.



## Application Overview



[Express](https://expressjs.com) is being used to receive requests.



[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.



This 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).



## File structure



- the infrastructure code is present in `.aws`

- the application code is in `src`

- `.circleci` contains circleCI setup

- `openapi.yml` contains api documentation



## Develop Locally



### First time setup



Clone the repo:



```bash

git clone [email protected]:Pocket/firefox-api-proxy.git

cd firefox-api-proxy

```



### Running tests



```bash

npm run test

```



### Testing locally



Start the server with:



```bash

npm ci

npm run start:dev

```



You will need authentication appropriate for the web V3 API deployment environment that is backing requests.



### E2E local testing with curl



Local E2E testing requires production Session Auth (cookie) authentication.



A helper script for generating authentication curl args can be found at [./scripts/scrapeCookie.js](./scripts/scrapeCookie.js).



Curl sample:



```bash

`curl 'http://localhost:4028/desktop/v1/recent-saves?count=1' `

```



### Leading with documentation, generated types



It is strongly suggested to lead implementation of features with changes to:



- `./openapi.yml`

- `./src/graphql-proxy/**/*.graphql`



These files are used to generate the types files in `./src/generated/*` with the following npm script:



```bash

npm run codegen

```



Upon 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.



## About errors in this service



All errors contain an `id`. These are just random strings that you can

search for in this repo to get more context on an error.



This service needs to provide an API for **every** version of Firefox that

ever gets deployed against this service. When a client receives a 5XX

error response, follow these guidelines:



- 500 Error

  - 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.

- 502 Error

  - 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:

    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.

    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.



All 5XX errors get recorded as events in sentry, and logged into

cloudwatch with correlating tags between the two.