{"id":21515418,"url":"https://github.com/danielfgray/api-helper","last_synced_at":"2025-04-09T20:12:22.760Z","repository":{"id":148817465,"uuid":"82655107","full_name":"DanielFGray/api-helper","owner":"DanielFGray","description":"curl profiles for working with apis","archived":false,"fork":false,"pushed_at":"2018-06-08T08:59:09.000Z","size":29,"stargazers_count":5,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T20:12:19.166Z","etag":null,"topics":["api","auth","bash","curl","helper","utility"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DanielFGray.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":"2017-02-21T08:28:14.000Z","updated_at":"2022-09-26T12:35:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"6f3e4825-e0b9-4b28-a020-20b4fea6d381","html_url":"https://github.com/DanielFGray/api-helper","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanielFGray%2Fapi-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanielFGray%2Fapi-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanielFGray%2Fapi-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanielFGray%2Fapi-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DanielFGray","download_url":"https://codeload.github.com/DanielFGray/api-helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103872,"owners_count":21048245,"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","auth","bash","curl","helper","utility"],"created_at":"2024-11-23T23:55:11.599Z","updated_at":"2025-04-09T20:12:22.749Z","avatar_url":"https://github.com/DanielFGray.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# api-helper\n\n## Dependencies\n\n* [curl](https://curl.haxx.se) for sending data\n* [`jq`](https://stedolan.github.io/jq/) *[optional]* for pretty-printing output and `--json` support (explained below)\n\n## Why\n\n* Many API tasks require sending the same headers or data with every request\n* Typing (or digging through your shell history for) the same options is tedious\n* You want to be able to save API requests (to your shell rc for example) without leaking your auth tokens everywhere\n* Using `curl --config` is clunky\n\n## Usage\n\n```\nusage: api [-vh] \u003cprofile\u003e \u003caction\u003e \u003cendpoint\u003e [...data]\n```\n\n* `profile` is the name of a file in `~/.config/api-helper` containing a URL entry and arbitrary curl options\n* `action` is an http verb like `get`, `put`, `post`, etc\n* `endpoint` is a route to be appended to the `url` defined in the `profile`\n* `data` are curl options like `--data`  to be sent with the request\n\nThere are three levels of verbosity:\n* `-v` will print the curl command to stderr\n* `-vv` will show the curl transfer status (by disabling `--silent`)\n* `-vvv` will call curl with `--verbose`\n\nVerbosity most be specified as the first argument.\n\n## Quick tutorial\n\n### GitHub\n\nAt minimum your profile should contain a URL entry:\n\n```\n~/.config/api-helper/github\n\nurl\t\thttps://api.github.com\n```\n\nYou'll likely also want to add authentication.\n\nThe [GitHub API](https://developer.github.com/guides/getting-started/) specifies you should provide an [access key](https://github.com/settings/tokens) as a header in the following form:\n\n```\nAuthorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4\n```\n\nso in the config file you would add\n\n```\nheader  Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4\n```\n\nYou can now query the API a lot simpler:\n\n```\napi github get user\n```\n\nWhich will execute\n\n````\ncurl --request GET --header 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' https://api.github.com/user\n````\n\nEverything after the first 3 arguments is passed directly to curl, so to pass data to the [API](https://developer.github.com/api/), you use curl's built-in methods.  \nCreating a repo on GitHub is now as simple as:\n\n```\napi github post user/repos -d '{\"name\":\"awesome_new_repo\"}'\n```\n\nOr, with some fancy [`jq`](https://stedolan.github.io/jq/) magic:\n\n```\napi github post user/repos --json '.name=\"awesome_new_repo\"'\n```\n\n`--json` is the only non-standard option currently provided, it's short-hand for `--data \"$(jq -Mcn '…')\"`\n\n### GitLab\n\nFor [GitLab](https://docs.gitlab.com/ce/api/README.html), the process is similar. Create a file at `~/.config/api-helper/gitlab` and put a `url` in there:\n\n```\nurl  https://gitlab.com/api/v4/\n```\n\nThe [auth for GitLab](https://docs.gitlab.com/ce/api/README.html#authentication) is only slightly different:\n\n```\nheader  PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK\n```\n\nYou should create [personal access token](https://gitlab.com/profile/personal_access_tokens) on Gitlab specifically for this this use, rather than using your private token.\n\nYou can of course specify multiple `header` entries, if you want to add `sudo` for example.\n\nYou can now [create new projects on GitLab](https://docs.gitlab.com/ce/api/projects.html#create-project) with\n\n```\napi gitlab post projects -d 'name=awesome_new_repo'\n```\n\n### Other\n\nIf the API you're using prefers HTTP auth you can specify a user in the config file: \n\n```\nurl   https://api.teknik.io/v1\nuser  user:password\n```\n\nOr if the API prefers it as a plain data key:\n\n```\nurl   http://ws.audioscrobbler.com/2.0/\ndata  api_key=dfd71eb15d3d76069d85617de769872a\ndata  format=json\n```\n\nAll of these options are taken from `man curl`; if you can pass it as an argument to `curl` you can save it as an option in the config file. Config files should be a sub-set of `curl` profiles described in the man page (I plan on a rewrite possibly in Perl that will allow full compatibility with existing profiles).\n\n## Shell Integration\n\nA small shell function can be added to your `bashrc` that will allow you to access the response as the variable `$res` in your shell:\n\n``` bash\napi() {\n  res=$(command api \"$@\")\n  echo \"$res\"\n}\n```\n\nOr if you'd like automatic pretty printing with `jq`:\n\n``` bash\napi() {\n  local json\n  res=$(command api \"$@\")\n  if json=$(jq -C '.' \u003c\u003c\u003c \"$res\" 2\u003e /dev/null); then\n    echo \"$json\"\n  else\n    echo \"$res\"\n  fi\n}\n```\n\n### Example Usage\n\n``` bash\n$ api github get users/danielfgray/repos\n$ jq -r '.[] | select(.fork == false) | \"\\(.html_url) \\(.description)\"' \u003c\u003c\u003c \"$res\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielfgray%2Fapi-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielfgray%2Fapi-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielfgray%2Fapi-helper/lists"}