{"id":23819854,"url":"https://github.com/kth/kth-node-api-call","last_synced_at":"2026-05-13T21:35:35.594Z","repository":{"id":38123804,"uuid":"67196207","full_name":"KTH/kth-node-api-call","owner":"KTH","description":"Node.js module to make JSON calls against APIs.","archived":false,"fork":false,"pushed_at":"2024-04-26T14:04:02.000Z","size":717,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":19,"default_branch":"main","last_synced_at":"2024-04-26T15:26:10.640Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KTH.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-02T06:27:18.000Z","updated_at":"2024-04-26T15:26:16.704Z","dependencies_parsed_at":"2024-04-26T15:26:12.384Z","dependency_job_id":"0a6195b7-c0c9-45cd-8d50-1ae9ef2801f2","html_url":"https://github.com/KTH/kth-node-api-call","commit_stats":{"total_commits":197,"total_committers":21,"mean_commits":9.380952380952381,"dds":0.7411167512690355,"last_synced_commit":"9a4e01a94fd50c1acfe0ef316778fcbb4776377e"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTH%2Fkth-node-api-call","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTH%2Fkth-node-api-call/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTH%2Fkth-node-api-call/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KTH%2Fkth-node-api-call/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KTH","download_url":"https://codeload.github.com/KTH/kth-node-api-call/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240100517,"owners_count":19747683,"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":"2025-01-02T07:16:05.847Z","updated_at":"2026-05-13T21:35:35.586Z","avatar_url":"https://github.com/KTH.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KTH API Call for Node\n\nNode module used to make JSON calls against APIs. (Previously published as `kth-node-api-call`, now `@kth/api-call`.)\n\nTo use in your node project, run:\n\n```sh\nnpm i @kth/api-call\n```\n\n## Setup\n\nIn your init callback to the Express web server, this should happen:\n\n```javascript\nconst connections = require('@kth/api-call').Connections\n\nconst nodeApi = {\n  namedApi: {\n    host: 'localhost', // api hostname\n    https: false, // use ssl?\n    port: 3001, // api port\n    proxyBasePath: '/api/applicationName', // api base path\n    required: true, // is the api required? Optional, defaults to false\n    defaultTimeout: 2000, // milliseconds. Optional, defaults to 2000\n  },\n}\n\nconst cacheConfig = {\n  namedApi: {\n    redis: {\n      host: 'localhost',\n      port: 6379,\n    },\n  },\n}\n\nconst apiKey = {\n  namedApi: '1234',\n}\n\nconst options = {\n  timeout: 5000, // milliseconds, retry interval if getting API-paths fails\n  log: myLogger, // your logger instance\n  redis: myRedis, // optional kth-node-redis instance\n  cache: cacheConfig, // your api cache options\n  checkAPIs: true,\n}\n// either\nmodule.exports = connections.setup(nodeApi, apiKey, options)\n// or\nconst api = connections.setup(nodeApi, apiKey, options)\n```\n\n### Note\n\nThe checkAPIs option requires that the API implements a checkAPIkey route, see [node-api](https://www.github.com/KTH/node-api.git)\nThe endpoint can be overridden by setting the `statusCheckPath` property on the api config object\n\n## Usage\n\nWherever you need to call your api, use something on the form of:\n\n```javascript\nconst paths = api.namedApi.paths\nconst client = api.namedApi.client\n\n// user is a uri parameter\nclient.getAsync(client.resolve(paths.[YOUR_ENDPOINT], {user: username, etc...}))\n.then(response =\u003e {\n  // do something with result\n})\n\n```\n\nif you want to use a cached api, add the option `{useCache: true}` to the `getAsync` call like this:\n\n```javascript\nclient.getAsync([FULL_PATH], { useCache: true }).then(response =\u003e {\n  // etc.\n})\n```\n\n## BasicAPI\n\nThis used to be a straightforward wrapper around [request][request]. Since version 4, `request` is replaced by [node-fetch][node-fetch], with efforts made to keep the same methods.\n\n`BasicAPI` will allow more control but also encourage more code re-use. It allows the use of Promises and caching (via redis) of successful responses (status \u003e= 200 and status \u003c 400).\n\nFor more details see the examples below and [the source code][basicjs].\n\n```javascript\n// configure this and re-use throughout your app\n\nconst api = new BasicAPI({\n  hostname: 'localhost',\n  port: 3001,\n  json: true,\n  https: false,\n  headers: {\n    api_key: 'abcd',\n  },\n  // optionally enable redis for response caching\n  // redis: {\n  //   client: redisClient,\n  //   prefix: 'node-api',\n  //   expire: 120\n  // }\n})\n\n// usage example:\n\nconst params = { id: 123 }\nconst uri = api.resolve('/value/:id', params)\n\n// promise\napi\n  .getAsync(uri)\n  .then(response =\u003e {\n    if (response.statusCode \u003e= 200 \u0026\u0026 response.statusCode \u003c 400) {\n      // do something with response.body\n    } else {\n      // bad/unexpected status code, delegate error\n    }\n  })\n  .catch(err =\u003e {\n    // handle/delegate err\n  })\n\n// or callback\napi.get(uri, (err, response, body) =\u003e {\n  if (err) {\n    // handle/delegate err\n    return\n  }\n\n  if (response.statusCode \u003e= 200 \u0026\u0026 response.statusCode \u003c 400) {\n    // do something with response.body\n  } else {\n    // bad/unexpected status code, delegate error\n  }\n})\n```\n\n### HTTP Request Methods\n\nEach of the following sends a corresponding HTTP request. Append `Async` (e.g. `getAsync`) to use Promise instead of callback. The first parameter should be either a uri (as a string) or an options object which is passed to [node-fetch][node-fetch]. For non-async methods the second parameter should be a function with the following signature: `function (error, response, body) { ... }`. The callback parameters are the same as for the request library.\n\nNote that if you use Redis and/or the async methods you might lose some functionality. For details about this, read the source code!\n\n- `get`/`getAsync`\n- `post`/`postAsync`\n- `put`/`putAsync`\n- `del`/`delAsync`\n- `head`/`headAsync`\n- `patch`/`patchAsync`\n\n### Utility Methods\n\n- `resolve` takes two parameters. The first is a uri template, e.g. `/value/:name`, and the second is a plain object, e.g. `{ name: 'foo' }`. It will then replace `:name` with the matching values in the object, resolving the uri `/value/foo`.\n- `defaults` re-uses the same config and applies another configuration set on top. Basically it does the same as `request.defaults()` but returns a valid `BasicAPI` instance.\n\n### Migration from version 3 to 4\n\n- `jar` and `cookie` were basic wrappers to the corresponding [request][request] methods. They were removed in version 4.\n- `defaults` was deprecated in version 4. Use `new BasicAPI(options)` instead.\n\n[request]: https://github.com/request/request\n[node-fetch]: https://github.com/node-fetch/node-fetch\n[basicjs]: ./basic.js\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkth%2Fkth-node-api-call","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkth%2Fkth-node-api-call","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkth%2Fkth-node-api-call/lists"}