{"id":18282848,"url":"https://github.com/intjelic/rodeo","last_synced_at":"2025-04-09T05:26:40.532Z","repository":{"id":150757102,"uuid":"337911404","full_name":"intjelic/rodeo","owner":"intjelic","description":"Cowboy handlers from HTTP API specifications.","archived":false,"fork":false,"pushed_at":"2021-02-19T05:09:43.000Z","size":80,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-14T23:48:38.962Z","etag":null,"topics":["cowboy","erlang","specs"],"latest_commit_sha":null,"homepage":"https://www.intjelic.me/projects/rodeo","language":"Erlang","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/intjelic.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":"2021-02-11T02:34:30.000Z","updated_at":"2022-09-21T14:23:10.000Z","dependencies_parsed_at":"2023-08-31T02:07:54.205Z","dependency_job_id":null,"html_url":"https://github.com/intjelic/rodeo","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/intjelic%2Frodeo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intjelic%2Frodeo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intjelic%2Frodeo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intjelic%2Frodeo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intjelic","download_url":"https://codeload.github.com/intjelic/rodeo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247983427,"owners_count":21028294,"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","specs"],"created_at":"2024-11-05T13:06:24.219Z","updated_at":"2025-04-09T05:26:40.507Z","avatar_url":"https://github.com/intjelic.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rodeo\n\n\u003e This is a work-in-progress; the Entity behavior was recently removed, making\npart of the docs irrelevant.\n\nFrom API specs to Cowboy handlers\n\nRodeo complements Cowboy with a generic handler and encourages you to implement\nan HTTP API from a well-defined specifications. The result is less intrusive\nas you are simply wrapping your existing regular Erlang functions and define\ntheir input and output.\n\n**Features**\n\n- Convert entities and actions...\n- ... to HTTP collections and resources\n- Exclusively JSON-oriented\n- Purposely very very very simple\n- ... and thus discarding some standards.\n- Built-in automatic API docs generator\n- It's a work-in-progress; it's evolving as personal need arise.\n\nWritten by **Jonathan De Wachter** on January 2021 and licensed under the\n**MIT license**.\n\n## Preview\n\nInstead of implementing Cowboy handlers, you implement the **Rodeo entity**\nbehavior. The `specs/0` function describes how the HTTP requests and responses\nmap to their 1:1 Erlang functions.\n\n```\n-module(hello)\n-behavior(rodeo_entity).\n-export([specs/0, hello/1]).\n\nspecs() -\u003e\n  #{\n    path =\u003e \"hello\",\n    actions =\u003e [\n      #{\n        type =\u003e collection,\n        path =\u003e no_path,\n        method =\u003e get,\n        input =\u003e [#{name =\u003e \"name\", type =\u003e string}],\n        output =\u003e [],\n        mfa =\u003e {?MODULE, hello, []}\n      }\n    ]\n  }.\n\nhello(Name) -\u003e\n    io:format(\"Hello ~s!~n\", [Name]).\n```\n\nLater, you're able to list all your entities in a master specifications in\norder to generate the **Cowboy routes**. Under the hood, it's using a **generic\nhandler** that is provided by Rodeo.\n\n```\nSpecs = #{\n    title    =\u003e \"My HTTP API\",\n    version  =\u003e {0, 1, 0},\n    entities =\u003e [hello]\n},\nRoutes = rodeo:generate_routes(Specs),\ncowboy:compile(Routes).\n```\n\nYour Erlang functions are called according to the specifications you gave and\nall the generic middleware logic is taken care for you. It includes\nauthentication, sanitizing the input, returning proper error messages. Also,\nit's JSON-oriented.\n\n```\nGET /api/v1/hello\n{\n  \"name\": \"world\"\n}\n```\n```\nHello world!\n```\n\n## Philosophy\n\nSome philosophy was followed when making a number of design decisions, and they\nmight or might not suit your need.\n\nWhile some strict standards emerged over the years (*OpenAPI* for instance),\nRodeo doesn't aim to fully comply with them. In fact, unless your API is used\nby thousands of other developers, there's little benefit in following them\nclosely and in practice, it takes a lot of energy. Nonetheless, it's important\nto meet some general expectation of an HTTP API and thus concepts like\nresources and collections as well as the meaning of each HTTP methods are\nimplemented. They're well explained in the [Rodeo documentation](/doc/overview.edoc).\n\nIt's also exclusively JSON-oriented; while some folks will find some very\nvalid arguments against it, it does the job; it's sufficiently fast and most\nimportantly, it yields elegant code. The resource IDs are put in the URL, but\nother than that, it's all exclusively in the JSON body.\n\nAlso Rodeo doesn't claim to be a perfect fit for all scenarios, but instead,\nclaims to be an efficient tool for most scenarios. Plus, it can easily be\ncombined by other tools. After all, it's merely providing a single generic\nCowboy handler and generate Cowboy routes for you; feel free to provide your\nown very custom routes and handlers.\n\n## Documentation\n\nThe documentation is all contained in `doc/overview.edoc` and an EDoc that\nincludes the API reference that can be generated with the `make edoc` command.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintjelic%2Frodeo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintjelic%2Frodeo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintjelic%2Frodeo/lists"}