feat: deprecating the dynamic api entrypoint (#723)

* feat: moving httpsnippet-client-api to native fetch * feat: moving to native fetch in api * fix: stop testing node 16 * feat: deprecating the dynamic `api` entrypoint * fix: cleaning up some remnants of the dynamic api * Update docs/faq.md Co-authored-by: Kanad Gupta <[email protected]> * fix: pr feedback --------- Co-authored-by: Kanad Gupta <[email protected]>
readmeio · Sep 12, 2023 · 437f6e4 · 437f6e4
1 parent 709c54b
commit 437f6e4
Show file tree

Hide file tree

Showing 63 changed files with 162 additions and 2,447 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -33,9 +33,6 @@ updates:
     ignore:
       # The following are packages that we're ignoring updates from because they've moved to being
       # ESM-only packages and we can't yet upgrade them.
-      - dependency-name: '@types/find-cache-dir'
-        versions:
-          - '>= 4'
       - dependency-name: chalk
         versions:
           - '>= 5'
@@ -45,9 +42,6 @@ updates:
       - dependency-name: figures
         versions:
           - '>= 4'
-      - dependency-name: find-cache-dir
-        versions:
-          - '>= 4'
       - dependency-name: get-stream
         versions:
           - '>= 7'

diff --git a/docs/faq.md b/docs/faq.md
@@ -5,7 +5,7 @@ category: 5d4c940cae4e610060475769
 
 ### Does this support YAML definitions?
 
-Yes! YAML definitions will be automatically converted to JSON when they're fetched for either SDK code generation or dynamic `api` usage.
+Yes! YAML definitions will be automatically converted to JSON when they're fetched.
 
 ### Does this support Swagger 2.0 definitions?
 
@@ -31,9 +31,7 @@ If you have ideas on how to handle this [we'd love to hear them](https://github.
 
 ### Will this work in browsers?
 
-If you generate an SDK with the CLI installation process then yes! If you're having trouble getting autogenerated SDKs working in a browser, [please let us know](https://github.com/readmeio/api/issues)!
-
-Unfortunately the dynamic version of `api` will **not** work in browsers as it requires access to the filesystem for handling and managing its cache state.
+Yes! However because `api` supports `multipart/form-data` requests and uploading files to APIs you may need to polyfill the `fs` module in your toolchain. If you're having trouble getting autogenerated SDKs working in a browser [please let us know](https://github.com/readmeio/api/issues)!
 
 ### Will this validate my data before it reaches the API?
 

diff --git a/docs/how-it-works.md b/docs/how-it-works.md
@@ -9,19 +9,13 @@ Behind the scenes, `api` will:
 2. Dereference the definition so it's easier for us to handle.
 3. Cache the definition so we don't need to re-fetch it.
 4. Process the definition into chainable methods for HTTP verbs and operation IDs.
-   - If you're using the code generation offering this only done at compilation time. If you're using the dynamic `api` offering this is done whenever you call `api` by way of a JavaScript [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy).
 
 ## Fetching
 
 At its core, `api` is a syntactical sugar wrapper for the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and the [HAR specification](http://www.softwareishard.com/blog/har-12-spec/). Parameters and payloads are compiled into a HAR according to the OpenAPI definition in question, using [@readme/oas-to-har](https://npm.im/@readme/oas-to-har) and then executed with [fetch-har](https://npm.im/fetch-har).
 
 ## Caching
 
-Depending on the way you're using `api`, either dynamically or with code generation, there are two caching mechanisms in place:
-
-- CLI code generation: `.api/`
-- Dynamic usage: `node_modules/.cache/api`
-
 ### `.api/` directory
 
 The `.api/` directory is where the CLI installation process stores all of its information: installation records, OpenAPI definitions, and code generated libraries. Its structure is as such:
@@ -66,54 +60,3 @@ The `api.json` file within `.api/` is where the CLI keeps track of everything th
 ```
 
 In the future, commands will be added to the CLI that will take advantage of this information, but for now it's only used to determine if you've already installed an API to the same `identifier` (say, to prevent you from installing `@developers/v2.0#nysezql0wwo236` twice).
-
-### `node_modules/.cache/api`
-
-Because the dynamic version of `api` cannot have access to the `identifier` system that the CLI installation process does, the dynamic version of `api` has a slightly different caching mechanism and stores its data within `node_modules/.cache/api`:
-
-```
-.node_modules/
-└── .cache/
-    └── api/
-        ├── cache.json           // Similar to `api.json` this is a record of
-        |                        // everything installed.
-        └── specs/
-            └── cbb821db3609f8983ce1a372dadd122c.json
-```
-
-> ⚠️
->
-> Note that because the dynamic version of `api` requires a filesystem and the Node `crypto` module, `api` cannot be used in the browser. If you need to use it in a browser we recommend you use the code generation avenue instead.
-
-#### `cache.json`
-
-The `cache.json` file in `node_modules/.cache/api` is where the dynamic version of API stores and pulls all of its data from. OpenAPI definitions are indexed within this file by their original acessor (`require('api')('http://example.com/some-accessor')`).
-
-The `hash` within this is an `md5` of the full OpenAPI definition that we retrieved.
-
-If for some reason this file gets lost, or the accessor you're supplying to `api` changes for whatever reason `api` will re-retrieve the OpenAPI definition at run-time.
-
-```json
-{
-  "d6b93e95fa1a7efdce6d1406dc599923": {
-    "hash": "cbb821db3609f8983ce1a372dadd122c",
-    "original": "https://dash.readme.com/api/v1/api-registry/nysezql0wwo236",
-    "title": "API Endpoints",
-    "version": "2.0.0"
-  }
-}
-```
-
-#### Custom cache directory
-
-By default the cache is configured with the [find-cache-dir](https://npm.im/find-cache-dir) library so the cache will be in `node_modules/.cache/api`. If placing this cache within the `node_modules/` directory is a problem for your environment (e.g. if you use `npm prune`), you can customize this by supplying an additional argument to the `api` instantiator:
-
-```js
-const sdk = require('api')('https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json', {
-  cacheDir: './path/to/my/custom/cache/dir',
-});
-
-sdk.listPets().then(({ data })) => {
-  console.log(`My pets name is ${data[0].name}!`);
-});
-```
diff --git a/docs/installation.md b/docs/installation.md
@@ -17,9 +17,3 @@ The `api` installer will guide you through several prompts about what kind of pr
 - URLs
   - You can also access and supply the URL for your ReadMe API Registry entry by using https://dash.readme.com/api/v1/api-registry/{uuid}, where `{uuid}` is the last part of your registry entry string. So in `@developers/v2.0#nysezql0wwo236` that would be `nysezql0wwo236`.
 - Local file paths
-
-To use the dynamic version of `api`, install the package to your project dependencies:
-
-```shell
-$ npm install api --save
-```
diff --git a/docs/making-requests.md b/docs/making-requests.md
@@ -5,12 +5,6 @@ category: 62cc6ce22b8b6601da6cb12d
 
 If the API you're using doesn't have any documented [operation IDs](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#user-content-operationid), `api` will generate some for you to use.
 
-If you're using code generation, these will be immediately available to use in your generated library. However, due to the nature of the [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) architecture in the dynamic version of the library, this isn't the case for dynamically generated libraries. For these cases, you can check out the documentation for the API you're using.
-
-> ⚠️
->
-> We recommend using code generation as it'll give you the additional benefit of TypeScript type assistance and autocompletion (even if you aren't using TypeScript in your codebase).
-
 With an instance of your SDK, you make an HTTP request against an operation on the API like so:
 
 ```js

diff --git a/docs/upgrading-from-v4.md b/docs/upgrading-from-v4.md
@@ -1,5 +1,5 @@
 ---
-title: Upgrading from v4
+title: Upgrading from v4 to v5
 category: 5d4c940cae4e610060475769
 ---
 

diff --git a/docs/usage.md b/docs/usage.md
@@ -3,8 +3,6 @@ title: Usage
 category: 5d4c940cae4e610060475769
 ---
 
-`api` can be used in two ways: a locally-installed code-generated library or dynamically.
-
 ## Code generation
 
 The code generation installation process that `api` offers comes in the form of an `api` CLI that will:
@@ -31,36 +29,3 @@ petstore.listPets().then(({ data, status, headers, res }) => {
 And if you use an IDE with TypeScript support (like [Visual Studio Code](https://code.visualstudio.com/)), you get the benefit of having autogenerated TypeScript types to help you out—regardless if you're actually using TypeScript!
 
 ![TypeScript types in action](https://raw.githubusercontent.com/readmeio/api/main/docs/images/ts-types.png)
-
-## Dynamically
-
-If you don't wish to use code generation, you can load `api` and supply it an OpenAPI definition directly:
-
-```js
-const petstore = require('api')('https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore.json');
-
-petstore.listPets().then(({ data, status, headers, res }) => {
-  console.log(`My pets name is ${data[0].name}!`);
-});
-```
-
-Alternatively, you can use the ESM syntax:
-
-```js
-import api from 'api';
-const petstore = api('@petstore/v1.0#tl1e4kl1cl8eg8');
-
-petstore.listPets().then(({ data, status, headers, res }) => {
-  console.log(`My pets name is ${data[0].name}!`);
-});
-```
-
-The OpenAPI definition is automatically downloaded, cached, and transformed into a chainable [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) Promise that you can use to make API requests.
-
-> 📘
->
-> By using the dynamic, non-code-generated version of `api`, you will not have access to any TypeScript types to assist you in using an API.
-
-> ⚠️
->
-> Using the dynamic version version of `api` will also gate you off you from using the library in a browser as the dynamic version of `api` requires access to a filesystem for the library to work.
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/api/README.md b/packages/api/README.md
@@ -36,18 +36,6 @@ petstore.listPets().then(({ data }) => {
 });
 ```
 
-Or you can use it dynamically (though you won't have fancy TypeScript types to help you out!):
-
-```js
-const petstore = require('api')(
-  'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json',
-);
-
-petstore.listPets().then(({ data }) => {
-  console.log(`My pets name is ${data[0].name}!`);
-});
-```
-
 The ESM syntax is supported as well:
 
 ```js

diff --git a/packages/api/example.js b/packages/api/example.js
diff --git a/packages/api/package.json b/packages/api/package.json
@@ -2,8 +2,6 @@
   "name": "api",
   "version": "6.1.1",
   "description": "Magical SDK generation from an OpenAPI definition 🪄",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "bin": {
     "api": "./bin/api"
   },
@@ -47,7 +45,6 @@
     "execa": "^5.1.1",
     "fetch-har": "^10.0.0",
     "figures": "^3.2.0",
-    "find-cache-dir": "^3.3.1",
     "get-stream": "^6.0.1",
     "js-yaml": "^4.1.0",
     "json-schema-to-ts": "^2.9.2",
@@ -70,7 +67,6 @@
   "devDependencies": {
     "@readme/oas-examples": "^5.12.0",
     "@types/caseless": "^0.12.3",
-    "@types/find-cache-dir": "^3.2.1",
     "@types/js-yaml": "^4.0.5",
     "@types/lodash.camelcase": "^4.3.7",
     "@types/lodash.deburr": "^4.1.7",