From fbc20dc18e82a7c558408b297256bba3402957e6 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Tue, 21 Dec 2021 09:15:16 +0100 Subject: [PATCH 1/3] ADR: Use node-fetch for data fetching Signed-off-by: Johan Haals --- .../adr013-use-node-fetch.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/architecture-decisions/adr013-use-node-fetch.md diff --git a/docs/architecture-decisions/adr013-use-node-fetch.md b/docs/architecture-decisions/adr013-use-node-fetch.md new file mode 100644 index 0000000000..8a6f61545d --- /dev/null +++ b/docs/architecture-decisions/adr013-use-node-fetch.md @@ -0,0 +1,22 @@ +--- +id: adrs-adr013 +title: 'ADR013: Use node-fetch for data fetching' +description: Architecture Decision Record (ADR) for HTTP data fetching packages +--- + +## Context + +Using multiple HTTP packages for data fetching increases the complexity and the +support burden of keeping said package up to date. + +## Decision + +Node packages should use the `node-fetch` package for HTTP data fetching. +Isomorphic packages should use the `cross-fetch` as a development dependency and +rely on the built-in `fetch` API. + +## Consequences + +We will gradually transition away from third party packages such as `axios`, +`got` and others. Once we have transitioned to `node-fetch` we will add lint +rules to enforce this decision. From e5703a34829635733bd66c0c54e36c7b6bd59741 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Tue, 21 Dec 2021 11:21:04 +0100 Subject: [PATCH 2/3] Add fetch examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Johan Haals --- .../adr013-use-node-fetch.md | 59 +++++++++++++++++-- 1 file changed, 54 insertions(+), 5 deletions(-) diff --git a/docs/architecture-decisions/adr013-use-node-fetch.md b/docs/architecture-decisions/adr013-use-node-fetch.md index 8a6f61545d..d802988ae4 100644 --- a/docs/architecture-decisions/adr013-use-node-fetch.md +++ b/docs/architecture-decisions/adr013-use-node-fetch.md @@ -1,7 +1,8 @@ --- id: adrs-adr013 -title: 'ADR013: Use node-fetch for data fetching' -description: Architecture Decision Record (ADR) for HTTP data fetching packages +title: 'ADR013: Proper use of HTTP fetching libraries' +# prettier-ignore +description: Architecture Decision Record (ADR) for the proper use of fetchApiRef, node-fetch, and cross-fetch for data fetching. --- ## Context @@ -11,9 +12,57 @@ support burden of keeping said package up to date. ## Decision -Node packages should use the `node-fetch` package for HTTP data fetching. -Isomorphic packages should use the `cross-fetch` as a development dependency and -rely on the built-in `fetch` API. +Backend (node) packages should use the `node-fetch` package for HTTP data +fetching. Example: + +```ts +import fetch from 'node-fetch'; +import { ResponseError } from '@backstage/errors'; + +const response = await fetch('https://example.com/api/v1/users.json'); +if (!response.ok) { + throw await ResponseError.fromResponse(response); +} +const users = await response.json(); +``` + +Frontend plugins and packages should prefer to use the +[`fetchApiRef`](https://backstage.io/docs/reference/core-plugin-api.fetchapiref). +It uses `cross-fetch` internally. Example: + +```ts +import { useApi } from '@backstage/core-plugin-api'; +const { fetch } = useApi(fetchApiRef); + +const response = await fetch('https://example.com/api/v1/users.json'); +if (!response.ok) { + throw await ResponseError.fromResponse(response); +} +const users = await response.json(); +``` + +Isomorphic packages should have a dependency on the `cross-fetch` package for +mocking and type definitions. Preferably, classes and functions in isomorphic +packages should accept an argument of type `typeof fetch` to let callers supply +their preferred implementation of `fetch`. This lets them adorn the calls with +auth or other information, and track metrics etc, in a cross-platform way. +Example: + +```ts +import crossFetch from 'cross-fetch'; + +export class MyClient { + private readonly fetch: typeof crossFetch; + + constructor(options: { fetch?: typeof crossFetch }) { + this.fetch = options.fetch || crossFetch; + } + + async users() { + return await this.fetch('https://example.com/api/v1/users.json'); + } +} +``` ## Consequences From 6bad2cfbd3f0c11034a3c70cf8f3e5724f2bbaf0 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 28 Dec 2021 14:14:46 +0100 Subject: [PATCH 3/3] docs: add adrs to sidebar and mkdocs Signed-off-by: Patrik Oldsberg --- microsite/sidebars.json | 3 ++- mkdocs.yml | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 89eb282d14..d342012f18 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -285,7 +285,8 @@ "architecture-decisions/adrs-adr009", "architecture-decisions/adrs-adr010", "architecture-decisions/adrs-adr011", - "architecture-decisions/adrs-adr012" + "architecture-decisions/adrs-adr012", + "architecture-decisions/adrs-adr013" ], "FAQ": ["FAQ"] } diff --git a/mkdocs.yml b/mkdocs.yml index 2eed377819..dfa4f461d1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -185,6 +185,8 @@ nav: - ADR009 - Entity References: 'architecture-decisions/adr009-entity-references.md' - ADR010 - Luxon Date Library: 'architecture-decisions/adr010-luxon-date-library.md' - ADR011 - Plugin Package Structure: 'architecture-decisions/adr011-plugin-package-structure.md' + - ADR012 - Plugin Package Structure: 'architecture-decisions/adr012-use-luxon-locale-and-date-presets.md' + - ADR013 - Plugin Package Structure: 'architecture-decisions/adr013-use-node-fetch.md' - Support: - Backstage Project Structure: 'support/project-structure.md' - Glossary: glossary.md