{"id":19662924,"url":"https://github.com/pustovitdmytro/base-api-client","last_synced_at":"2025-10-23T23:12:55.645Z","repository":{"id":43029400,"uuid":"362931391","full_name":"pustovitDmytro/base-api-client","owner":"pustovitDmytro","description":"Base API client backed by axios","archived":false,"fork":false,"pushed_at":"2025-04-27T22:40:58.000Z","size":2065,"stargazers_count":3,"open_issues_count":16,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-27T23:26:14.920Z","etag":null,"topics":["api","axios","base","class","rest-api"],"latest_commit_sha":null,"homepage":"","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/pustovitDmytro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"pustovit"}},"created_at":"2021-04-29T19:53:22.000Z","updated_at":"2024-10-31T18:47:20.000Z","dependencies_parsed_at":"2024-01-25T12:29:28.253Z","dependency_job_id":"636d9649-29b5-41dc-9b7c-81aa658bc4eb","html_url":"https://github.com/pustovitDmytro/base-api-client","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/pustovitDmytro/base-api-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pustovitDmytro%2Fbase-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pustovitDmytro%2Fbase-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pustovitDmytro%2Fbase-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pustovitDmytro%2Fbase-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pustovitDmytro","download_url":"https://codeload.github.com/pustovitDmytro/base-api-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pustovitDmytro%2Fbase-api-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265233753,"owners_count":23731825,"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":["api","axios","base","class","rest-api"],"created_at":"2024-11-11T16:12:48.913Z","updated_at":"2025-10-23T23:12:50.627Z","avatar_url":"https://github.com/pustovitDmytro.png","language":"JavaScript","readme":"![Logo](.docs/logo_250.png \"Base API client\")\n# base-api-client\nBase API client backed by [axios](https://www.npmjs.com/package/axios).\n\n[![Version][badge-vers]][npm]\n[![Bundle size][npm-size-badge]][npm-size-url]\n[![Downloads][npm-downloads-badge]][npm]\n\n[![CodeFactor][codefactor-badge]][codefactor-url]\n[![SonarCloud][sonarcloud-badge]][sonarcloud-url]\n[![Codacy][codacy-badge]][codacy-url]\n[![Scrutinizer][scrutinizer-badge]][scrutinizer-url]\n\n[![Dependencies][badge-deps]][npm]\n[![Security][snyk-badge]][snyk-url]\n[![Build Status][tests-badge]][tests-url]\n[![Coverage Status][badge-coverage]][url-coverage]\n\n[![Commit activity][commit-activity-badge]][github]\n[![FOSSA][fossa-badge]][fossa-url]\n[![License][badge-lic]][github]\n[![Made in Ukraine][ukr-badge]][ukr-link]\n\n## 🇺🇦 Help Ukraine\nI woke up on my 26th birthday at 5 am from the blows of russian missiles. They attacked the city of Kyiv, where I live, as well as the cities in which my family and friends live. Now my country is a war zone. \n\nWe fight for democratic values, freedom, for our future! Once again Ukrainians have to stand against evil, terror, against genocide. The outcome of this war will determine what path human history is taking from now on.\n\n💛💙  Help Ukraine! We need your support! There are [dozen ways][ukr-link] to help us, just do it!\n\n## Table of Contents\n- [base-api-client](#base-api-client)\n  - [🇺🇦 Help Ukraine](#-help-ukraine)\n  - [Table of Contents](#table-of-contents)\n  - [Requirements](#requirements)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [Constructor arguments](#constructor-arguments)\n    - [Methods](#methods)\n  - [Implementations](#implementations)\n  - [Contribute](#contribute)\n\n## Requirements\n[![Platform Status][node-ver-test-badge]][node-ver-test-url]\n\nTo use library you need to have [node](https://nodejs.org) and [npm](https://www.npmjs.com) installed in your machine:\n\n* node `\u003e=10`\n* npm `\u003e=6`\n\nPackage is [continuously tested][node-ver-test-url] on darwin, linux and win32 platforms. All active and maintenance [LTS](https://nodejs.org/en/about/releases/) node releases are supported.\n\n## Installation\n\nTo install the library run the following command\n\n```bash\n  npm i --save base-api-client\n```\n\n## Usage\n\nExample of [telegram](https://telegram.org/) client extended from BaseAPI:\n\n```javascript\nimport BaseAPI from 'base-api-client';\n\nexport default class TelegramAPI extends BaseAPI {\n    constructor(id, token) {\n        super(`https://api.telegram.org/${id}:${token}`);\n    }\n\n    message(chatId, html) {\n        return this.post('sendMessage', {\n            'parse_mode' : 'HTML',\n            'text'       : html,\n            'chat_id'    : chatId\n        });\n    }\n\n    file(chatId, fileId) {\n        return this.post('sendDocument', {\n            'document' : fileId,\n            'chat_id'  : chatId\n        });\n    }\n}\n\n```\n\n### Constructor arguments\n\n  1. **url** - base URL of the API. Can consist apiPrefix. Will be cast to nodeJS URL object.\n  2. **options** - object with next attributes:\n      * **timeout** - timeout in [ms](https://www.npmjs.com/package/ms) format. Will be cast to integer (in milliseconds). **Default**: 1m.\n      * **logger** - if applied, will add *debug* and *verbose* messages before and after each request. Should have next interface: ```logger.log(level, object)```.\n\n### Methods\n\n**HTTP methods**:\n\n* `get(url, params, options)`\n* `post(url, data, options)`\n* `patch(url, data, options)`\n* `put(url, data, options)`\n* `delete(url, options)`\n\nin all aforementioned methods `url` can be both global, or relative to base URL (defined in [constructor](#constructor-arguments)). `params` are url query params, and `data` is JSON body. `options` are passed directly to [axios request](https://github.com/axios/axios#request-config)\n\n**Headers**\n\nImplement `getHeaders()` method to define select headers for API. Alternativelly, pass headers in `options` for each request if headers need behave differently.\n\n**Basic auth**\nuse `auth` setting, if you want to use basic auth for each request.\n\n```javascript\nthis.auth = {\n    username : '',\n    password : ''\n};\n```\n\n**Data processing**\n\nNext methods can be used for default data pre/post-processing:\n\n```javascript\n        onError(error) {\n            if (error.isAxiosError) {\n                throw new API_ERROR(error);\n            }\n            throw error;\n        },\n\n        onResponse(res) {\n            return res.data;\n        }\n```\n\n**Errors**\n\nthe package exposes `API_ERROR`, that can be used outside:\n\n```javascript\nimport BaseAPI, { API_ERROR } from 'base-api-client';\n\nclass API extends BaseAPI {\n    constructor() {\n        super('http://wiwbif.is/fugo');\n    }\n\n    async createUser(email) {\n        try {\n            const user = await this.post('/users', { email });\n\n\n            return user.id;\n        } catch (error) {\n            if (error instanceof API_ERROR) {\n                console.log('raw http error:', error.payload);\n                throw error;\n            }\n        }\n    }\n}\n```\n\n**Logging and Tracing**\n\nYou can pass **logger** while [api creation](#constructor-arguments), but also this can be done by calling `initLogger(logger)` method directly.\n\nAlternatively, use polymorphism and implement the `log(level, data)` method on descendants. \n\nAutogenerated **Trace ID** is atached to each log. If you need control over traceId generation, implement `getTraceId(reqOptions, settings)` method.\n\n**Testing**\n\nDepending on selected approach use  `setMock(mockFuction)` or implement `_axios(axiosOptions)` method. Both `mockFuction` and `_axios` will receive axios options instead of axios instance, and should return expected result. Default mock function is `() =\u003e ({ data: 1 })`. \n\nTo check examples of api mocks and tesing, see [implementation](#implementations) section.\n\n\n## Implementations\n\nLooking for more examples? Check real implementations of famous APIs:\n\n| API | Organization | Reference |  Examples |\n|----|---|----------|-----|\n| [Telegram Bot](https://web.telegram.org) | Telegram | [Bot API ](https://core.telegram.org/bots/api) | \u003cul\u003e\u003cli\u003e [sns-telegram-bot](https://github.com/pustovitDmytro/sns-telegram-bot/blob/master/src/api/TelegramApiClient.js) \u003c/li\u003e\u003cli\u003e [semantic-release-telegram](https://github.com/pustovitDmytro/semantic-release-telegram/blob/master/src/telegram/TelegramAPI.js) \u003c/li\u003e\u003c/ul\u003e\n| [Telegra.ph](https://telegra.ph/) | Telegram | [Telegraph API](https://telegra.ph/api) | \u003cul\u003e\u003cli\u003e[semantic-release-telegram](https://github.com/pustovitDmytro/semantic-release-telegram)\u003c/li\u003e\u003c/ul\u003e\n| [AWS SNS](https://aws.amazon.com/sns) | Amazon | [AWS docs](https://docs.aws.amazon.com/sns/latest/api/welcome.htmli) | \u003cul\u003e\u003cli\u003e[sns-telegram-bot](https://github.com/pustovitDmytro/sns-telegram-bot/blob/master/src/api/AWSApiClient.js)\u003c/li\u003e\u003c/ul\u003e\n| [Gitea](https://gitea.io) |  | [Gitea Swagger](https://try.gitea.io/api/swagger#/) | \u003cul\u003e\u003cli\u003e[lalaps](https://github.com/pustovitDmytro/lalaps/blob/master/src/api/GiteaAPI.js)\u003c/li\u003e\u003c/ul\u003e\n| [GitHub Apps](https://github.com/) | Microsoft | [Apps Reference](https://docs.github.com/en/rest/reference/apps) | \u003cul\u003e\u003cli\u003e[lalaps](https://github.com/pustovitDmytro/lalaps/blob/master/src/api/GithubAppAPI.js)\u003c/li\u003e\u003c/ul\u003e\n| [GitHub Repos](https://github.com/) | Microsoft | [Repositories Reference](https://docs.github.com/en/rest/reference/repos) | \u003cul\u003e\u003cli\u003e[lalaps](https://github.com/pustovitDmytro/lalaps/blob/master/src/api/GithubReposAPI.js)\u003c/li\u003e\u003c/ul\u003e\n| [Heroku](https://www.heroku.com/home) | Salesforce | [Platform API Reference](https://devcenter.heroku.com/articles/platform-api-reference) | \u003cul\u003e\u003cli\u003e[semantic-release-heroku](https://github.com/pustovitDmytro/semantic-release-heroku/blob/master/src/heroku/HerokuApi.js)\u003c/li\u003e\u003c/ul\u003e\n| [JIRA](https://www.atlassian.com/software/jira) | Atlassian | [REST API](https://developer.atlassian.com/server/jira/platform/rest-apis/) | \u003cul\u003e\u003cli\u003e[atlassian](https://github.com/pustovitDmytro/atlassian/blob/master/src/api/JiraApi.js)\u003c/li\u003e\u003c/ul\u003e\n| [Confluence](https://www.atlassian.com/software/confluence)  | Atlassian | [REST API](https://developer.atlassian.com/server/confluence/confluence-server-rest-api/) | \u003cul\u003e\u003cli\u003e[atlassian](https://github.com/pustovitDmytro/atlassian/blob/master/src/api/ConfluenceApi.js)\u003c/li\u003e\u003c/ul\u003e\n\n## Contribute\n\nMake the changes to the code and tests. Then commit to your branch. Be sure to follow the commit message conventions. Read [Contributing Guidelines](.github/CONTRIBUTING.md) for details.\n\n[npm]: https://www.npmjs.com/package/base-api-client\n[github]: https://github.com/pustovitDmytro/base-api-client\n[coveralls]: https://coveralls.io/github/pustovitDmytro/base-api-client?branch=master\n[badge-deps]: https://img.shields.io/librariesio/release/npm/base-api-client.svg\n[badge-vuln]: https://img.shields.io/snyk/vulnerabilities/npm/base-api-client.svg?style=popout\n[badge-vers]: https://img.shields.io/npm/v/base-api-client.svg\n[badge-lic]: https://img.shields.io/github/license/pustovitDmytro/base-api-client.svg\n[badge-coverage]: https://coveralls.io/repos/github/pustovitDmytro/base-api-client/badge.svg?branch=master\n[url-coverage]: https://coveralls.io/github/pustovitDmytro/base-api-client?branch=master\n\n[snyk-badge]: https://snyk-widget.herokuapp.com/badge/npm/base-api-client/badge.svg\n[snyk-url]: https://snyk.io/advisor/npm-package/base-api-client\n\n[tests-badge]: https://img.shields.io/circleci/build/github/pustovitDmytro/base-api-client\n[tests-url]: https://app.circleci.com/pipelines/github/pustovitDmytro/base-api-client\n\n[codefactor-badge]: https://www.codefactor.io/repository/github/pustovitdmytro/base-api-client/badge\n[codefactor-url]: https://www.codefactor.io/repository/github/pustovitdmytro/base-api-client\n\n[commit-activity-badge]: https://img.shields.io/github/commit-activity/m/pustovitDmytro/base-api-client\n\n[scrutinizer-badge]: https://scrutinizer-ci.com/g/pustovitDmytro/base-api-client/badges/quality-score.png?b=master\n[scrutinizer-url]: https://scrutinizer-ci.com/g/pustovitDmytro/base-api-client/?branch=master\n\n[codacy-badge]: https://app.codacy.com/project/badge/Grade/d8f448ed725149cb8ee80b4b608621ef\n[codacy-url]: https://www.codacy.com/gh/pustovitDmytro/base-api-client/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=pustovitDmytro/base-api-client\u0026amp;utm_campaign=Badge_Grade\n\n[sonarcloud-badge]: https://sonarcloud.io/api/project_badges/measure?project=pustovitDmytro_base-api-client\u0026metric=alert_status\n[sonarcloud-url]: https://sonarcloud.io/dashboard?id=pustovitDmytro_base-api-client\n\n[npm-downloads-badge]: https://img.shields.io/npm/dw/base-api-client\n[npm-size-badge]: https://img.shields.io/bundlephobia/min/base-api-client\n[npm-size-url]: https://bundlephobia.com/result?p=base-api-client\n\n[node-ver-test-badge]: https://github.com/pustovitDmytro/base-api-client/actions/workflows/npt.yml/badge.svg?branch=master\n[node-ver-test-url]: https://github.com/pustovitDmytro/base-api-client/actions?query=workflow%3A%22Node.js+versions%22\n\n[fossa-badge]: https://app.fossa.com/api/projects/custom%2B24828%2Fbase-api-client.svg?type=shield\n[fossa-url]: https://app.fossa.com/projects/custom%2B24828%2Fbase-api-client?ref=badge_shield\n\n[ukr-badge]: https://img.shields.io/badge/made_in-ukraine-ffd700.svg?labelColor=0057b7\n[ukr-link]: https://war.ukraine.ua\n","funding_links":["https://patreon.com/pustovit"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpustovitdmytro%2Fbase-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpustovitdmytro%2Fbase-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpustovitdmytro%2Fbase-api-client/lists"}