{"id":15651250,"url":"https://github.com/johannschopplich/apiful","last_synced_at":"2025-04-09T07:06:01.495Z","repository":{"id":222533497,"uuid":"757528235","full_name":"johannschopplich/apiful","owner":"johannschopplich","description":"🍷 Extensible, typed API tooling — from generated OpenAPI clients to server-side utilities, for any JavaScript runtime","archived":false,"fork":false,"pushed_at":"2025-03-24T12:59:28.000Z","size":1090,"stargazers_count":61,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-02T13:18:46.725Z","etag":null,"topics":["api-client","ofetch","openapi","openapi-generator","unjs"],"latest_commit_sha":null,"homepage":"https://apiful.byjohann.dev","language":"TypeScript","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/johannschopplich.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2024-02-14T17:15:33.000Z","updated_at":"2025-03-24T12:59:31.000Z","dependencies_parsed_at":"2024-02-14T20:14:42.817Z","dependency_job_id":"d799bad4-c848-4043-8fce-926ef0211c4a","html_url":"https://github.com/johannschopplich/apiful","commit_stats":{"total_commits":134,"total_committers":1,"mean_commits":134.0,"dds":0.0,"last_synced_commit":"67e7569bd387a4d67ee733c7ab536489668d8018"},"previous_names":["johannschopplich/apiverse","johannschopplich/apiful"],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johannschopplich%2Fapiful","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johannschopplich%2Fapiful/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johannschopplich%2Fapiful/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johannschopplich%2Fapiful/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johannschopplich","download_url":"https://codeload.github.com/johannschopplich/apiful/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247994119,"owners_count":21030050,"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-client","ofetch","openapi","openapi-generator","unjs"],"created_at":"2024-10-03T12:37:40.291Z","updated_at":"2025-04-09T07:06:01.466Z","avatar_url":"https://github.com/johannschopplich.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![APIful library](./docs/public/og.png)](https://apiful.byjohann.dev)\n\n# APIful\n\n[![npm version][npm-version-src]][npm-version-href]\n\nAPIful provides a unified interface to manage all your API interactions by setting up a client with default fetch options, such as the base API URL and headers. Extensions add a variety of features to the client to match your favorite flavor of API management.\n\nYou can use one of the [built-in extensions](https://apiful.byjohann.dev/guide/using-extensions#built-in-extensions) to get started right away, or create your own [custom extension](https://apiful.byjohann.dev/guide/custom-extensions) to meet your specific needs.\n\n## Setup\n\n\u003e [!TIP]\n\u003e [📖 Read the documentation](https://apiful.byjohann.dev)\n\n```bash\n# pnpm\npnpm add -D apiful\n\n# npm\nnpm i -D apiful\n```\n\n## Usage\n\n\u003e [!TIP]\n\u003e [📖 Read the documentation](https://apiful.byjohann.dev)\n\n### Your First API Client\n\nCreate your first API client by initialising it with a base URL and a sample bearer token for authorization:\n\n```ts\nimport { createClient } from 'apiful'\n\nconst baseURL = '\u003cyour-api-base-url\u003e'\nconst client = createClient({\n  baseURL,\n  headers: {\n    Authorization: `Bearer ${process.env.API_KEY}`,\n  },\n})\n```\n\n\u003e [!NOTE]\n\u003e The `createClient` function returns an [`ApiClient`](https://apiful.byjohann.dev/reference/api-client) instance that does not yet have a call signature. You will need to add a base extension to the client in order to make API requests. Read on to learn how to do this.\n\n### Built-in Extensions\n\n\u003ctable\u003e\u003ctr\u003e\u003ctd width=\"500px\" valign=\"top\"\u003e\n\n### `ofetchBuilder`\n\n```ts\nimport { createClient, ofetchBuilder } from 'apiful'\n\nconst baseURL = '\u003cyour-api-base-url\u003e'\nconst adapter = ofetchBuilder()\nconst api = createClient({ baseURL }).with(adapter)\n\n// GET request to \u003cbaseURL\u003e/users/1\nawait api('users/1', { method: 'GET' })\n```\n\n\u003c/td\u003e\u003ctd width=\"500px\"\u003e\u003cbr\u003e\n\n**What it does:**\n\nThe `ofetchBuilder` wraps [ofetch](https://github.com/unjs/ofetch) to handle API requests.\n\n\u003c/td\u003e\u003c/tr\u003e\u003ctr\u003e\u003ctd width=\"500px\" valign=\"top\"\u003e\n\n### `apiRouterBuilder`\n\n```ts\nimport { apiRouterBuilder, createClient } from 'apiful'\n\nconst baseURL = '\u003cyour-api-base-url\u003e'\nconst adapter = apiRouterBuilder()\nconst api = createClient({ baseURL }).with(adapter)\n\n// GET request to \u003cbaseURL\u003e/users/1\nawait api.users.get(1)\n// POST request to \u003cbaseURL\u003e/users with payload\nawait api.users.post({ name: 'foo' })\n```\n\n\u003c/td\u003e\u003ctd width=\"500px\"\u003e\u003cbr\u003e\n\n**What it does:**\n\nThe `apiRouterBuilder` provides a jQuery-like and Axios-esque API for building and making API requests. It allows you to construct your API calls in a declarative way.\n\n\u003c/td\u003e\u003c/tr\u003e\u003ctr\u003e\u003ctd width=\"500px\" valign=\"top\"\u003e\n\n### `OpenAPIBuilder`\n\n```ts\nimport { createClient, OpenAPIBuilder } from 'apiful'\n\nconst baseURL = 'https://petstore3.swagger.io/api/v3'\n// Pass pre-generated schema type ID to adapter\nconst adapter = OpenAPIBuilder\u003c'petStore'\u003e()\nconst api = createClient({ baseURL }).with(adapter)\n\n// Typed parameters and response\nconst response = await api('/user/{username}', {\n  method: 'GET',\n  path: { username: 'user1' },\n})\n```\n\n\u003c/td\u003e\u003ctd width=\"500px\"\u003e\u003cbr\u003e\n\n**What it does:**\n\nIf your API has an [OpenAPI](https://swagger.io/resources/open-api/) schema, APIful can use it to generate types for you, which the `OpenAPIBuilder` extension then consumes to provide type-safe API calls.\n\nFor example, the response returned by the API call on the left is typed as follows:\n\n```ts\nconst response: {\n  id?: number\n  username?: string\n  // …\n}\n```\n\nFollow the [OpenAPI extension documentation](https://apiful.byjohann.dev/extensions/openapi) to learn more about how to generate TypeScript definitions from your OpenAPI schema files.\n\n\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\n### Custom Extensions\n\nEach client can have more than one extension. This means that you can chain `with` methods to add multiple extensions to your client.\n\nFor example, you can add a custom extension to log the default fetch options:\n\n```ts\nimport type { MethodsExtensionBuilder } from 'apiful'\n\nconst logExtension = (client =\u003e ({\n  logDefaults() {\n    console.log('Default fetch options:', client.defaultOptions)\n  }\n})) satisfies MethodsExtensionBuilder\n\nconst extendedClient = client\n  .with(logExtension)\n\nextendedClient.logDefaults() // { baseURL: '\u003cyour-base-url\u003e', headers: { Authorization: 'Bearer \u003cyour-bearer-token\u003e' } }\n```\n\nIf you have specific requirements that are not covered by the included extensions, you can create your own extensions. Follow the [Custom Extensions](https://apiful.byjohann.dev/guide/custom-extensions) guide to learn more.\n\n## Development\n\n- Clone this repository\n- Install latest LTS version of [Node.js](https://nodejs.org/en/)\n- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`\n- Install dependencies using `pnpm install`\n- Run interactive tests using `pnpm test`\n\n## License\n\nMade with 💛\n\nPublished under [MIT License](./LICENSE).\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/apiful?style=flat\n[npm-version-href]: https://npmjs.com/package/apiful\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohannschopplich%2Fapiful","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohannschopplich%2Fapiful","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohannschopplich%2Fapiful/lists"}