{"id":23069096,"url":"https://github.com/el1s7/rests","last_synced_at":"2025-07-04T22:37:10.245Z","repository":{"id":44346693,"uuid":"302090358","full_name":"el1s7/rests","owner":"el1s7","description":"Easily generate API client's SDK — organize and simplify API Requests — OOP-ish way.","archived":false,"fork":false,"pushed_at":"2024-03-18T14:02:51.000Z","size":194,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-18T17:06:30.781Z","etag":null,"topics":["api","api-sdk-generator","api-wrapper","fetch","fetch-api","get","http","openapi","post","request","requests","rest","rest-api","schema","sdk","subcategories","swagger"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/el1s7.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":"2020-10-07T16:08:23.000Z","updated_at":"2023-05-12T01:50:41.000Z","dependencies_parsed_at":"2024-06-19T05:42:56.478Z","dependency_job_id":null,"html_url":"https://github.com/el1s7/rests","commit_stats":null,"previous_names":["elis-k/wrape"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/el1s7/rests","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/el1s7%2Frests","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/el1s7%2Frests/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/el1s7%2Frests/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/el1s7%2Frests/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/el1s7","download_url":"https://codeload.github.com/el1s7/rests/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/el1s7%2Frests/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260721688,"owners_count":23052241,"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-sdk-generator","api-wrapper","fetch","fetch-api","get","http","openapi","post","request","requests","rest","rest-api","schema","sdk","subcategories","swagger"],"created_at":"2024-12-16T06:12:55.346Z","updated_at":"2025-07-04T22:37:10.222Z","avatar_url":"https://github.com/el1s7.png","language":"TypeScript","readme":"  \n\n# Rests\n\nWork with requests in a modern and beautiful way.\n\n\nEasily generate API client's SDK — organize and simplify HTTP Requests.\n\n\n\n### An API Request with Rests✅\n\n```javascript\napi.login({\n\tuser: 'test',\n\tpassword: 'test'\n})\n.then(({json})=\u003e(\n\tconsole.log(`Logged in!`)\n));\n```\n\n### Normal API Request❌\n ```javascript\nfetch(\"https://example.com/login\",{\n\t'method': 'POST',\n\t'headers': {\n\t\t'Content-Type': 'application/x-www-form-urlencoded'\n\t},\n\t'data': `user=${user}\u0026password=${password}`\n}).then((res) =\u003e (if(!res.ok){ return Promise.reject(\"error\"))})\n.then((res) =\u003e res.json())\n.catch((err) =\u003e console.warn)\n.then(data)=\u003e (console.log(\"Finally the response\")));\n```\n\n\n## Features\n\n- One source of truth for all your API requests\n- Robust configuration, makes it easier to handle validation, authentication, and hooks\n- Complex inheritance, split requests into multiple categories/subcategories and prevent repetition\n- Generate Typescript \u003cimg src='https://i.imgur.com/C6sVrY1.png' style='vertical-align:middle' /\u003e  types for your API automatically\n- Generate a simple markdown reference automatically\n- Supports schema from pure JSON \n- Universal support - works on Browsers \u0026 Node.js\n- 🪐 **Private edition only**: Generate Python API with type hints\n- 🪐 **Private edition only**: Generate Beautiful documenation website, with complete request and response examples, and OpenAPI schema definitions\n\n\n\u0026 more\n\n\n\n\n## Installation\n\n`npm i rests`\n\nYou should also install it globally in order to easily run the cli.\n\n`npm i rests -g`\n\n  \n## Import\n\nRecommended\n```javascript\nimport Rests from 'rests';\n```\n\n### With CommonJS\nImport it like this to get the Types \u0026  Intellisense suggestions on CommonJS\n```javascript\nconst Rests = require(\"rests\").default;\n```\n\n\n## Usage\n```javascript\nimport Rests from 'rests';\n\nconst API = Rests({\n\t$options: {\n\t\tbase: 'https://example.com'\n\t},\n\tuser:{\n\t\tlogin:{\n\t\t\tpath: '/user/login',\n\t\t\tmethod: 'POST',\n\t\t\tparams:{\n\t\t\t\tusername:{\n\t\t\t\t\trequired: true,\n\t\t\t\t\ttype: \"string\",\n\t\t\t\t\thelp: \"A valid username is required\",\n\t\t\t\t\tvalidate: /\\w+/\n\t\t\t\t},\n\t\t\t\tpassword: {\n\t\t\t\t\trequired:  true,\n\t\t\t\t\thelp: \"A valid password is required\",\n\t\t\t\t\ttype: \"string\",\n\t\t\t\t\t\n\t\t\t\t\tformat: (password) =\u003e { \n\t\t\t\t\t\tif(password.length \u003c 8){\n\t\t\t\t\t\t\tthrow new Error(\"The password must be at least 8 characters.\");\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn password;\n\t\t\t\t\t}\n\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t\tprofile: {\n\t\t\t$options:{\n\t\t\t\tparams:{\n\t\t\t\t\t//Set authentication parameters for all requests in this category\n\t\t\t\t\tauthorization: {...} \n\t\t\t\t}\n\t\t\t}\n\t\t\tinfo: {\n\t\t\t\t...\n\t\t\t},\n\t\t\tupdate: {\n\t\t\t\t...\n\t\t\t}\n\t\t}\n\t}\n});\n\nexport default API;\n\n```\n\n### Then you can call your API like this\n\n```javascript\nimport API from './API.js';\n\nAPI.user.login({\n\tusername: 'nice',\n\tpassword: 'mypassword'\n})\n.then((res)=\u003e{\n\tconsole.log(res.json);\n\t//Successful Response, body automatically parsed.\n})\n.catch((res)=\u003e{\n\tconsole.log(res.json || res.message);\n\t//Error Response \n})\n```\n\n### Example Validation error\n```javascript\nimport API from './API.js';\n\nAPI.user.login({\n\tusername: 'john', \n\tpassword: 'short'\n}).catch((err) =\u003e {\n\tconsole.log(err.field, err.message); \n\t//Prints: password The password must be at least 8 characters.\n});\n\n```\n### Initialization and Setting Variables\n\nA category is like a class instance, you can intialize it with new values/options.\n\nYou can set parameter values for all requests in a category scope\n\n```javascript\nconst User = new api.user({\n\tauthorization: 'user_auth_token'\n}); \n\n```\n\nYou can also update the options for a category by using the special `$options` key\n```javascript\nconst User = new api.user({\n\t$options: {\n\t\ton_error: (error)=\u003e{\n\t\t\tif(error?.statusCode == 401){\n\t\t\t\talert(\"Session has expired\");\n\t\t\t}\n\t\t}\n\t}\n}); \n```\n\n## CLI Usage\nRests comes with a simple CLI for generating types and API markdown reference.\n\nGenerate the types file `./api.d.ts` automatically and watch for changes\n```bash\n\u003e rests ./api.js --types --watch\n```\n\n\nGenerate the markdown API refrence\n```bash\n\u003e rests ./api.js --docs\n```\n\n## Rests with automatic typings in action\n\u003cimg src='https://i.imgur.com/nQGSyaf.png'\u003e\n\n\n\n##  Projects using Rests \n[TikAPI](https://tikapi.io) is using Rests:\n\n- https://github.com/tikapi-io/tiktok-api\n\n\n## TODO\n- [ ] Support `cookie` as parameter location\n- [ ] Support raw body requests without parameters (e.g `API.user(rawBodyBytes)`)\n- [ ] Feature: Store cookie jar and persist session cookies over requests (same as python requests lbirary)\n\n\n## Schema Reference\n\n#### Categories\n An API category is an object consisting of [Endpoint Object](#endpoint-object)s or subcategories.\nA category can also contain these special keys:\n  - **`$options`**: Options for this category and it's subcategories, overriding other options. See [Options](#options)\n  - **`help`**:  A  description of the category.\n\n#### Endpoint Object\n - **`path`**: The request path or full URL, which can also contain named parameters. \n  - **`method`**: The request method, GET,POST etc. *(default: GET)*\n  - **`enctype`**: The body encode type for \\*only for *requests that have body* parameters:\n\t - **`json`**` (application/json)` *(default)*\n\t - **`form`**` (multipart/form-data)` \n\t - **`urlencode`**` (application/x-www-form-urlencoded)`\n  - **`params`**: An object consisting of [Params Object](#params-object)s.\n  - **`help`**: A description of this endpoint\n  - **`example_response`**: Example response used for documentation generation\n  - **`on_success`**: See [Options](#options) \n  - **`on_error`**: See [Options](#options)\n  - **`on_request`**: See [Options](#options)\n  - **`$other`**: Any other custom option you may need to include\n \n\n#### Params Object\n - **`name`**: The parameter HTTP name, this defaults to the object key name.\n - **`required`**: `boolean` *(default: false)*.\n - **`help`**: A helpful message to throw if the parameter is invalid.\n - **`type`**: Supported types:\n     - **`\"string\"`** \n     - **`\"number\"`** \n     - **`\"array\"`** \n     - **`\"object\"`** \n     - **`\"boolean\"`** \n     - **`\"any\"`** *(default)*\n\n - **`format`**: A function to format the parameter value, or throw an error if it's invalid.\n - **`validate`**: Regex validation.\n - **`default`**: A default value.\n - **`location`**: The location where this parameter will be in the HTTP request fields:\n     - **`body`** the param will be included in request body *(default for POST request)*\n     - **`query`** the param will be URL encoded in request URL query *(default for GET request)*\n     - **`headers`** the param will be included in request headers\n     - **`path`** the param will be included in request path\n       - Note: You must also declare the named parameter key in the Endpoint path like `/get/{key}`. \n  - **``example``** : Example values used for documentation generation\n  - **`in`**:  Array of allowed values\n  - **`max`**: Maximum allowed value for number types\n  - **`min`**: Minimum allowed value for number types\n\n###  Options\nThe options object can be defined in every category using the special `$options` key, all the subcatgories will inherit them.\n\n`Rested(endpoints, options?)`\n  - **`base`**: This will be prepended before each requests path. (e.g `https://example.com`)\n  - **`sandboxBase`**: For sandbox requests.\n  - **`headers`**: Key-value object of headers to include in all requests\n  - **`params`**: Params to include in all requests\n  - **`values`**: Key-value object store to set default values for all parameters\n  - **`on_request`**: A global hook function that is called before each request. Accepts an object of `{url, options, params, key, instance, self}` where self is the current method function.\n\t\n\tTo modify the request:\n\t```javascript \n\treturn {url, options}\n\t``` \n\t\n\tTo prevent the request from sending:\n\t```javascript \n\treturn false\n\t```\n\n  - **`on_success`**: A hook function that is called on successful response, you can also modify and return a different response. Accepts `(response, request)`.\n  - **`on_error`**: A hook function that is called on errors. Accepts `(error_response, request)`. You can also return a new error like this:\n\t```javascript\n\treturn Promise.reject(CustomErrorResponse)\n\t```\n  - **`fetch_agent`**: You can use this option to configure proxy if you're using node-fetch. \n  - **`proxies`**: Requests proxies dict, for python version only.\n  - **`$other`**: Any other custom option you may need to include","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fel1s7%2Frests","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fel1s7%2Frests","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fel1s7%2Frests/lists"}