{"id":28543857,"url":"https://github.com/inaka/cowboy-trails","last_synced_at":"2025-07-06T18:32:04.477Z","repository":{"id":34152495,"uuid":"37991203","full_name":"inaka/cowboy-trails","owner":"inaka","description":"A couple of improvements over Cowboy Routes","archived":false,"fork":false,"pushed_at":"2024-06-10T05:39:50.000Z","size":1042,"stargazers_count":71,"open_issues_count":0,"forks_count":21,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-05-06T17:23:41.712Z","etag":null,"topics":["cowboy","erlang","hacktoberfest","trails"],"latest_commit_sha":null,"homepage":"http://inaka.github.io/cowboy-trails/","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"ml5js/ml5-examples","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inaka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-06-24T14:55:05.000Z","updated_at":"2025-05-01T09:36:27.000Z","dependencies_parsed_at":"2024-05-22T09:46:36.385Z","dependency_job_id":"d8f80323-391b-4f8e-9473-d10350d2a37d","html_url":"https://github.com/inaka/cowboy-trails","commit_stats":{"total_commits":181,"total_committers":22,"mean_commits":8.227272727272727,"dds":0.6353591160220995,"last_synced_commit":"8bd861f5ed0e10398f476cccbe0abe92fb6f6178"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fcowboy-trails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fcowboy-trails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fcowboy-trails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fcowboy-trails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inaka","download_url":"https://codeload.github.com/inaka/cowboy-trails/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inaka%2Fcowboy-trails/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258828283,"owners_count":22763941,"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":["cowboy","erlang","hacktoberfest","trails"],"created_at":"2025-06-09T22:06:03.101Z","updated_at":"2025-07-06T18:32:04.472Z","avatar_url":"https://github.com/inaka.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://lh5.googleusercontent.com/-Y1n1Vh4FjLE/TXDZiQ_zSVI/AAAAAAAAAJY/h47az_0MxO0/s1600/Western+backdrop+04.png\" height=\"200\" width=\"100%\" /\u003e\n\n# cowboy-trails\n\n![build](https://github.com/inaka/cowboy-trails/workflows/build/badge.svg)\n\nCowboy routes on steroids!\n\n## Contact Us\n\nIf you find any **bugs** or have a **problem** while using this library, please\n[open an issue](https://github.com/inaka/cowboy-trails/issues/new) in this repo\n(or a pull request 😄).\n\nAnd you can check out all of our open-source projects at [inaka.github.io](https://inaka.github.io).\n\n## Why Cowboy Trails?\n\n**Cowboy-Trails** enables you to:\n\n* add information to `cowboy` routes, which can later be used to interact with\n  the server in a higher abstraction level,\n* define the server routes directly within the module that implements them.\n\n## How to Use it?\n\nThe most common use case for `cowboy_trails` is to compile `cowboy` routes.\n\nNormally with `cowboy` you compile routes in the following way:\n\n```erlang\nRoutes = [{'_',\n           [ {\"/resource1\", resource1_handler, []}\n           , {\"/resource2/[:id]\", resource2_handler, []}\n           ]\n          }\n         ],\ncowboy_router:compile(Routes),\n```\n\nTrails is fully compatible with `cowboy` routes, so you can pass the same\nroutes in order to be processed by Trails:\n\n```erlang\ntrails:compile(Routes),\n```\n\nSo far it seems like there's no difference, right? But most of the time,\nwith `cowboy`, you usually work with only a single host, but you're\nrequired to keep defining the host parameter within the routes (`[{'_', [...]}]`).\n\nWell, with Trails you have another useful function to compile single host routes:\n\n```erlang\n%% You only define the routes/paths\nRoutes = [ {\"/resource1\", resource1_handler, []}\n         , {\"/resource2/[:id]\", resource2_handler, []}\n         ],\ntrails:single_host_compile(Routes),\n```\n\nNow, let's suppose you want to add metadata to\n`cowboy` routes related with the semantics of each HTTP method.\n\nYou'd do something like:\n\n```erlang\nMetadata = #{put =\u003e #{description =\u003e \"PUT method\"},\n             post =\u003e #{description =\u003e \"POST method\"},\n             get =\u003e #{description =\u003e \"GET method\"}},\nTrail = trails:trail(\"/\",\n                     cowboy_static,\n                     {private_file, \"index2.html\"},\n                     Metadata,\n                     []),\n%% You can later retrieve the metadata:\nMetadata = trails:metadata(Trail),\n```\n\nThis can then be used to generate documentation related to each endpoint.\n\nAlso, when you work with `cowboy`, you have to define all routes in one place:\n\n```erlang\nRoutes =\n  [{'_',\n    [ {\"/\", cowboy_static, {file, \"www/index.html\"}}\n    , {\"/favicon.ico\", cowboy_static, {file, \"www/assets/favicon.ico\"}}\n    , {\"/assets/[...]\", cowboy_static, {dir, \"www/assets\"}}\n    , {\"/game/:game_id\", cowboy_static, {file, \"www/game.html\"}}\n    , {\"/api/status\", spts_status_handler,  []}\n    , {\"/api/games\", spts_games_handler, []}\n    , {\"/api/games/:game_id\", spts_single_game_handler, []}\n    , {\"/api/games/:game_id/serpents\", spts_serpents_handler, []}\n    , { \"/api/games/:game_id/serpents/:token\"\n      , spts_single_serpent_handler, []\n      }\n    , {\"/api/games/:game_id/news\", lasse_handler, [spts_news_handler]}\n    ]\n   }\n  ],\nDispatch = cowboy_router:compile(Routes),\n```\n\nBut now, with `trails`, you're able to define the routes on each of your resource handlers,\nseparately.\nThese handlers must implement callback `c:trails_handler:trails/0` or `c:trails_handler:trails/1`\nand return the specific\nroutes that define them. For a better understanding, you can check out the\nexamples in the `test` folder ([trails_test_handler](https://github.com/inaka/cowboy-trails/blob/master/test/trails_test_handler.erl)).\n\nOnce you have implemented the `c:trails_handler:trails/0` or `c:trails_handler:trails/1` callback\non your handlers, you can do\nsomething like this:\n\n```erlang\nHandlers =\n  [ spts_status_handler\n  , spts_games_handler\n  , spts_single_game_handler\n  , spts_serpents_handler\n  , spts_single_serpent_handler\n  , spts_news_handler\n  , {support_params_handler, #{key =\u003e value}}\n  ],\nTrails =\n  [ {\"/\", cowboy_static, {file, \"www/index.html\"}}\n  , {\"/favicon.ico\", cowboy_static, {file, \"www/assets/favicon.ico\"}}\n  , {\"/assets/[...]\", cowboy_static, {dir, \"www/assets\"}}\n  , {\"/game/:game_id\", cowboy_static, {file, \"www/game.html\"}}\n  | trails:trails(Handlers)\n  ],\ntrails:single_host_compile(Trails),\n```\n\nThis way each handler maintains their own routes, as it should be, and you can\nmerge them easily.\n\n## Example\n\nFor more information about `cowboy_trails`, how to use it and the different\nfunctions that it exposes, please check this [example](https://github.com/inaka/cowboy-trails/blob/master/example).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finaka%2Fcowboy-trails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finaka%2Fcowboy-trails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finaka%2Fcowboy-trails/lists"}