How does it work?
Behind the scenes, api
will:
- Fetch the supplied OpenAPI definition, either from a publically accessible URL, an absolute/relative path, or a ReadMe API Registry UUID.
- Dereference the definition so it's easier for us to handle.
- Cache the definition so we don't need to re-fetch it.
- 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 callapi
by way of a JavaScript Proxy.
- If you're using the code generation offering this only done at compilation time. If you're using the dynamic
Fetching
At its core, api
is a syntactical sugar wrapper for the Fetch API and the HAR specification. Parameters and payloads are compiled into a HAR according to the OpenAPI definition in question, using @readme/oas-to-har and then executed with 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
.api/
directoryThe .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:
.api/
├── api.json // The `package-lock.json` equivalent that records
| // everything that's installed, when it was installed,
| // what the original source was, and what version of
| // `api` was used.
└── apis/
├── readme/
| ├── node_modules/
│ ├── index.js
│ ├── index.d.ts // All types for the SDK, ready to use in your IDE.
│ |── openapi.json
│ └── package.json
└── petstore/
├── node_modules/
├── index.ts
├── index.d.ts
├── openapi.json
└── package.json
api.json
api.json
The api.json
file within .api/
is where the CLI keeps track of everything that's been installed. It's structure has been closely modeled after NPM's package-lock.json
file. For example, after running npx api install @developers/v2.0#nysezql0wwo236
:
{
"version": "1.0",
"apis": [
{
"identifier": "developers",
"source": "@developers/v2.0#nysezql0wwo236",
"integrity": "sha512-lQeYVerukls0IYy3Ys9J6Hri9nucH2zBZk6ehO1EI9a/0K3p/egoIw/Yz9A93KtB1KUUArjGK6ebqsZkHFxguA==",
"installerVersion": "5.0.0-beta.0"
}
]
}
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
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 Nodecrypto
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
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.
{
"d6b93e95fa1a7efdce6d1406dc599923": {
"hash": "cbb821db3609f8983ce1a372dadd122c",
"original": "https://dash.readme.io/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 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:
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}!`);
});
Updated 5 months ago