{"id":23170320,"url":"https://github.com/palanik/wrapi","last_synced_at":"2025-10-04T03:38:14.091Z","repository":{"id":57399726,"uuid":"44938813","full_name":"palanik/wrapi","owner":"palanik","description":":gift: Wrap Restful APIs as callable functions.","archived":false,"fork":false,"pushed_at":"2021-01-11T03:38:23.000Z","size":75,"stargazers_count":14,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-02T09:53:39.495Z","etag":null,"topics":["api","api-wrapper"],"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/palanik.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-26T01:33:00.000Z","updated_at":"2023-08-11T13:16:15.000Z","dependencies_parsed_at":"2022-08-29T18:52:00.077Z","dependency_job_id":null,"html_url":"https://github.com/palanik/wrapi","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palanik%2Fwrapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palanik%2Fwrapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palanik%2Fwrapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palanik%2Fwrapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/palanik","download_url":"https://codeload.github.com/palanik/wrapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230213197,"owners_count":18191138,"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","api-wrapper"],"created_at":"2024-12-18T03:26:42.150Z","updated_at":"2025-10-04T03:38:09.038Z","avatar_url":"https://github.com/palanik.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"wrapi\n=====\nWrap Restful API endpoints as callable functions.\n\nCreate a Rest API SDK under 3 minutes.\n\n[![NPM version](https://img.shields.io/npm/v/wrapi.svg?style=flat)](https://www.npmjs.org/package/wrapi)\n[![Build Status](https://img.shields.io/travis/palanik/wrapi.svg?style=flat)](https://travis-ci.org/palanik/wrapi)\n[![Coverage Status](https://coveralls.io/repos/palanik/wrapi/badge.svg?service=github)](https://coveralls.io/github/palanik/wrapi)\n[![Known Vulnerabilities](https://snyk.io/test/github/palanik/wrapi/badge.svg)](https://snyk.io/test/github/palanik/wrapi)\n\nWith **`wrapi`** you make calls to HTTP based APIs just like ordinary JavaScript functions.\n***\n\n## Installation\n\n```sh\n$ npm install wrapi --save\n```\n\nOr\n\n```sh\n$ yarn add wrapi\n```\n\n## Easy Start\n\n1. Create a [JSON file](#json-file) listing all API endpoints you want to work with.\n2. [Wrap](#wrap-endpoints) endpoints with **`wrapi`**.\n3. Call individual endpoints as [functions](#make-the-call).\n\nSee [Sample Code](examples/github/sample1.js)\n\n------\n\n### JSON File\nDeclare each endpoint in a json file as per the following specifications.\n\n```js\n\"function_name\": {\n\t\"method\": \"HTTP_METHOD\",\t\t\t\t\t// 'GET', 'POST', 'PUT', 'PATCH' or 'DELETE'\n\t\"path\": \"relative/path/to/:api/endpoint\"\t// Use `express` style path params\n}\n```\n\n E.g. a small set of github.com [API](https://developer.github.com/v3/repos/):\n```json\n{\n\t\"repo\": {\n\t\t\"method\" : \"GET\",\n\t\t\"path\" : \"repos/:owner/:repo\"\n\t},\n\n\t\"contributors\": {\n\t\t\"method\" : \"GET\",\n\t\t\"path\" : \"repos/:owner/:repo/contributors\"\n\t},\n\n\t\"languages\": {\n\t\t\"method\" : \"GET\",\n\t\t\"path\" : \"repos/:owner/:repo/languages\"\n\t},\n\n\t\"tags\": {\n\t\t\"method\" : \"GET\",\n\t\t\"path\" : \"repos/:owner/:repo/tags\"\n\t},\n\n\t\"branches\": {\n\t\t\"method\" : \"GET\",\n\t\t\"path\" : \"repos/:owner/:repo/branches\"\n\t}\n}\n```\n\n### Wrap endpoints\nCreate a API client object from **`wrapi`**. Provide the base url for the API and the JSON object.\n**`wrapi`** will create a client object with all the necessary functions.\n\n```js\nconst endpoints = require('./github.api.json');\nconst wrapi = require('wrapi');\n\nconst client = new wrapi('https://api.github.com/',\t// base url for the API\n  endpoints \t\t\t\t\t\t\t\t\t\t// your json object\n);\n\n// client object contains functions to call the API\n```\n\n### Register\nRegister additional API endpoints with the client object with a function name.\n\n```js\nclient.register('zen',\n  {\n    method : 'GET',\n    path: 'zen'\n  }\n);\n```\n\n### Make the call\nCall API function with arguments and a callback.\n\n```js\n// This will make GET request to 'https://api.github.com/repos/nodejs/node/contributors'\nclient.contributors('nodejs', 'node', function(err, contributors) {\n  if (!err) {\n  \tconsole.log(contributors);\n  }\n});\n\nclient.zen(function(err, response) {\n  if (!err) {\n    console.log('Chris says \"' + response + '\"');\n  }\n});\n\n```\n\n\n## API\n\n**`wrapi`** is an open ended framework. It is not restricted any specific or a set of APIs.\n\nAll APIs providing HTTP interface to access the endpoints can be wrapped by **`wrapi,`** so that you can quickly build your client application.\n\n### Endpoint Definition\n\nNote: `method` \u0026 `path`/`url` are required.\n\n* `method` - Any one of the HTTP [methods](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) (default: `\"GET\"`)\n* `path` - route path to API Endpoint. Supports `express` style [path params](http://expressjs.com/en/4x/api.html#req.params)\n* `query` - an object consists of name-value pairs. This is _optional_. This is useful where resources are identified via query string parameters\n* `options` - options to override or to add specific to the API endpoint. E.g. `{encoding:null}` returns the response data as `Buffer`\n* `url` - fully qualified uri string to override. This is useful in cases where an API call connects to a different endpoint\n\n\n### Client object\n\nThe **`wrapi`** object conveniently provides the client interface to the API. Create the object by calling `new` **`wrapi()`**.\n\nThe constructor takes the following arguments:\n\n1. `baseURL` - The base url for the API. E.g. `https://api.github.com/`\n2. `endpoints` - The JSON object listing the API endpoints. Provide `{}` - empty object or a partial list and then `register` (additional) endpoints later\n3. `options` - Optional parameter. **`wrapi`** uses [request](https://www.npmjs.com/package/request) module to connect to API server. The `options` parameter is the same [`options`](https://www.npmjs.com/package/request#requestoptions-callback) parameter used in `request`\n\n#### Custom options\n1. `catchHTTP4xx5xx` - Set this option to `true` to treat HTTP status 4xx \u0026 5xx as errors. Default value is `false`. If set, the `err` argument in your callback function will contain the response body for 4xx \u0026 5xx errors.\n\n### Register function\n\nAdd endpoints to client object.\n```\nregister(functionName, endpointDefinition)\n```\n\n1. `functionName` - Alias for the endpoint, also the name of the function to call.\n2. `endpointDefinition` - JSON object defining the endpoint.\n\n\n### Function calls\n\nCall API endpoints via the function in the client object.  Arguments to the function depend on the API declaration in the JSON.\n\nProvide the arguments in the following order:\n\n1. named `params` in the url path of the endpoint. eg. `client.contributors('nodejs', 'node',   // nodejs \u0026 node are path params`\n2. `query string` as an object with name-value pairs. eg. `client.repositories({since:364}  //  ?since=364`\n3. `body` - JSON content for  `POST` or `PUT` methods. Skip this argument if not required for the call.\n  * To **POST** `multipart/form-data`, set this argument as `{\"formData\" : multipartContent }`\n4. `callback(err, data)` - a callback function for the results to be returned. The callback is called when the response is fetched or if there is an error. This callback function gets the results of the response.\n\n    \u003e To `pipe` the results, pass a [writable stream](https://nodejs.org/api/stream.html#stream_class_stream_writable) as the callback.\n\t\tListen to `error` events on outputstream to catch streaming errors. See [example](examples/google/chartasstream.js).\n\n## Examples\n\n  In [examples](examples) folder.\n\n## Implementations\n\n* [Slack Web API](https://www.npmjs.com/package/slack-wrapi)\n* [Square Connect API](https://www.npmjs.com/package/square-wrapi)\n* [Medium](https://www.npmjs.com/package/medium-wrapi)\n* [Twitter REST APIs](https://www.npmjs.com/package/twitter-wrapi)\n* [Instagram API](https://www.npmjs.com/package/@wrapi/instagram)\n* [Genius API](https://www.npmjs.com/package/@wrapi/genius)\n* [GIPHY API](https://www.npmjs.com/package/giphy-wrapi)\n* [Riffsy's API](https://www.npmjs.com/package/riffsy)\n* [Pokémon API](https://www.npmjs.com/package/pokemon-wrapi)\n\n## License\n\n  [MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalanik%2Fwrapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpalanik%2Fwrapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalanik%2Fwrapi/lists"}