{"id":18464676,"url":"https://github.com/norfairking/template-api-server-with-auth-and-cli","last_synced_at":"2025-04-08T08:31:12.075Z","repository":{"id":67628003,"uuid":"304826339","full_name":"NorfairKing/template-api-server-with-auth-and-cli","owner":"NorfairKing","description":"A template implementation of an API server with an example command-line tool to go along with it","archived":false,"fork":false,"pushed_at":"2024-12-01T21:19:15.000Z","size":296,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-23T09:11:40.783Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://template.cs-syd.eu/template/NorfairKing/template-api-server-with-auth-and-cli","language":"Haskell","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/NorfairKing.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-17T07:52:33.000Z","updated_at":"2024-12-01T21:19:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"bbabe609-f8af-4d7b-abcf-a1bfe773aba9","html_url":"https://github.com/NorfairKing/template-api-server-with-auth-and-cli","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/NorfairKing%2Ftemplate-api-server-with-auth-and-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorfairKing%2Ftemplate-api-server-with-auth-and-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorfairKing%2Ftemplate-api-server-with-auth-and-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorfairKing%2Ftemplate-api-server-with-auth-and-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NorfairKing","download_url":"https://codeload.github.com/NorfairKing/template-api-server-with-auth-and-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247804403,"owners_count":20998973,"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":[],"created_at":"2024-11-06T09:10:44.491Z","updated_at":"2025-04-08T08:31:11.649Z","avatar_url":"https://github.com/NorfairKing.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# API Server with CLI Template\n\nThis is a template implementation of an API server with an example command-line tool to go along with it.\nIt features complete option parsing, like in [template-optparse](https://github.com/NorfairKing/template-optparse), a command-line tool like in [template-cli](https://github.com/NorfairKing/template-cli) as well as  handlers, testing and best-practices.\n\n* Haskell code for an api-server\n* Per-route integration tests for the api-server\n* Haskell code for an accompanying command-line tool\n* Per-command integration test for the cli tool\n* Option parsing \u0026 Option parsing tests for both the server and the cli tool\n* Stack build\n* Cabal build\n* Nix build\n* Statically linked Nix build\n* Test Coverage report\n* Weeder check\n* NixOS module for hosting the server\n* Nix home manager module for using the client\n* Flake-based CI\n* Pre-commit hooks\n  * hlint\n  * hpack\n  * nixpkgs-fmt\n  * ormolu\n\n## License\n\nThis template is **not** free to use.\nSee https://template.cs-syd.eu/template/NorfairKing/template-api-server-with-auth-and-cli for more information.\n\nCopyright (c) 2020-2024 Tom Sydney Kerckhove.\n\nAll Rights Reserved.\n\n## Instructions\n\nTo use this template in a new project, choose the name for your project, for example `homeless-shelter`.\nThen use [template-filler](https://github.com/NorfairKing/template-filler) to use the template, like this:\n\n```\ntemplate-filler --source /path/to/this/template-api-server-with-auth-and-cli --destination /path/to/your/homeless-shelter --find FooBar --replace HomelessShelter\n```\n\n### Template overview\n\nThis template contains these haskell packages and notable modules:\n\n- `foo-bar-api`: The API, as a `servant`-based type definition, and related data types.\n  - `Foo/Bar.API.Data`: The API data type definitions\n  - `Foo/Bar.API`: The API Type definition\n- `foo-bar-api-gen`: The generators and tests for the API and its data types.\n  - `FooBar.API.Data.Gen`: Generators for the API data types\n- `foo-bar-api-server`: The API server that implements this API.\n  - `Foo/Bar.API.Server.OptParse`: Option parsing\n  - `Foo/Bar.API.Server.Env`: The (read-only) environment and related functions\n  - `Foo/Bar.API.Server.Handler.\u003cCommandName\u003e`: One module per command of the CLI.\n- `foo-bar-api-server-gen`: The generators and tests for the API server.\n  - `Foo/Bar.API.Server.TestUtils`: Utility functions to write tests that use the API server\n  - `Foo/Bar.API.Server.Handler.\u003cCommandName\u003eSpec`: One module per handler containing its tests\n- `foo-bar-client`: The client record of functions to call the API server.\n  - The `Foo/Bar.Client.foo-barClient` record.\n- `foo-bar-cli`: An example command-line tool to call the API server.\n  - `Foo/Bar.CLI.OptParse`: Option parsing\n  - `Foo/Bar.CLI.Env`: The (read-only) environment and related functions\n  - `Foo/Bar.CLI.Command.\u003cCommandName\u003e`: One module per command of the CLI.\n\n\n![Dependency graph](dependencies.png)\n\n### OptParse\n\nThe option parsing for both `foo-bar-cli` and `foo-bar-api-server` is based on [the option parsing template](https://github.com/NorfairKing/template-optparse).\nIt is included in this template so you will not need to also buy the option parsing template.\n\nFor more information about how to use the option parsing, follow the instructions in `template-cli/src/Foo/Bar/Cli/OptParse.hs`.\n\n### Nix build\n\nIf you don't need a nix build, remove these files:\n\n```\nrm -rf *.nix nix\n```\n\nThe project overlay is defined in `nix/overlay.nix`.\n\nIn `nix/nixos-module.nix`, we define a NixOS module for hosting the server.\nIn `nix/home-manager-module.nix`, we define a nix home manager module for using the project on NixOS.\nIn `nix/nixos-module-test.nix`, both of those are tested. This test is not run on CI because GitHub actions does not support it.\n\nSee the instructions in `nix/overlay.nix` for more details.\n\n### Workflow examples\n\n#### Adding an endpoint to the API\n\n1. Add the endpoint in `foo-bar-api/src/Foo/Bar/API.hs`.\n2. Add a handler module in `foo-bar-api-server/src/Foo/Bar/API/Server/Handler/\u003cRouteName\u003ehs` with a function as follows:\n\n   ```\n   handle\u003cRouteName\u003e :: H ()\n   ```\n\n   Give it a type according to the endpoint type.\n   If it requires authentication, add `AuthCookie` as the first argument.\n\n3. Hook up the handler in the `foo-barHandlers` record in `foo-bar-api-server/src/Foo/Bar/API/Server.hs`.\n\n   If the endpoint requires authentication, use the `protected` combinator.\n\n4. Add tests in `foo-bar-api-server-gen/test/Foo/Bar/API/Server/Handler/\u003cRouteName\u003eSpec.hs`\n\n#### Adding a command to the CLI tool\n\n1. Add the new command's option parsing in the `Foo/Bar.CLI.OptParse` module according to the instructions within.\n\n2. Add a `Foo/Bar.CLI.Command.\u003cCommandName\u003e` module with a function as follows:\n\n   ```\n   commandName :: CommandNameSettings -\u003e C ()\n   ```\n\n3. Add a case to the `dispatch` function in `Foo/Bar.CLI`.\n4. Add tests in `Foo/Bar.CLI.Command.\u003cCommandName\u003eSpec`.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorfairking%2Ftemplate-api-server-with-auth-and-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnorfairking%2Ftemplate-api-server-with-auth-and-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorfairking%2Ftemplate-api-server-with-auth-and-cli/lists"}