{"id":19435465,"url":"https://github.com/goadesign/goa-cellar","last_synced_at":"2025-04-24T21:30:32.695Z","repository":{"id":57479677,"uuid":"47490014","full_name":"goadesign/goa-cellar","owner":"goadesign","description":"goa winecellar example service","archived":false,"fork":false,"pushed_at":"2018-01-05T00:00:37.000Z","size":11370,"stargazers_count":86,"open_issues_count":3,"forks_count":31,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-06-18T17:05:16.527Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://swagger.goa.design/?url=github.com/goadesign/goa-cellar/design","language":"Go","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/goadesign.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}},"created_at":"2015-12-06T09:01:44.000Z","updated_at":"2023-03-20T14:17:40.000Z","dependencies_parsed_at":"2022-09-26T20:00:43.085Z","dependency_job_id":null,"html_url":"https://github.com/goadesign/goa-cellar","commit_stats":null,"previous_names":["raphael/goa-cellar"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goadesign%2Fgoa-cellar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goadesign%2Fgoa-cellar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goadesign%2Fgoa-cellar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goadesign%2Fgoa-cellar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goadesign","download_url":"https://codeload.github.com/goadesign/goa-cellar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223968408,"owners_count":17233445,"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-10T15:06:33.620Z","updated_at":"2024-11-10T15:06:34.225Z","avatar_url":"https://github.com/goadesign.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# goa Cellar\n\nThe goa winecellar service provides an example for the [goa](http://goa.design) web application\nframework.\n\nThe service implements an API for managing wine bottles. The service is multitenant: bottles are\ncreated in the context of an account. At this time the database is emulated with a in-memory hash.\nAn instance of this example is hosted at http://cellar.goa.design.\n\n## Usage\n\n### Calling the Hosted Service\n\nUsing the excellent [httpie client](https://github.com/jkbrzt/httpie):\n\nListing bottles in account 1:\n```bash\nhttp http://cellar.goa.design/cellar/accounts/1/bottles\nHTTP/1.1 200 OK\nContent-Length: 707\nContent-Type: application/vnd.goa.example.bottle+json; type=collection; charset=utf-8\nDate: Sun, 06 Dec 2015 09:06:10 GMT\nServer: Google Frontend\nVary: Origin\n\n[\n    {\n        \"href\": \"/cellar/accounts/1/bottles/100\",\n        \"id\": 100,\n        \"links\": {\n            \"account\": {\n                \"href\": \"/cellar/accounts/1\",\n                \"id\": 1,\n                \"name\": \"account 1\"\n            }\n        },\n        \"name\": \"Number 8\",\n        \"rating\": 4,\n        \"varietal\": \"Merlot\",\n        \"vineyard\": \"Asti Winery\",\n        \"vintage\": 2012\n    },\n# ...\n```\n\nCreating a new account:\n```bash\nhttp POST http://cellar.goa.design/cellar/accounts name=sonoma created_by=me\nHTTP/1.1 201 Created\nContent-Length: 0\nContent-Type: text/html; charset=utf-8\nDate: Sun, 06 Dec 2015 09:08:55 GMT\nLocation: /cellar/accounts/3\nServer: Google Frontend\nVary: Origin\n```\n\nShowing the newly created account:\n```bash\nhttp  http://cellar.goa.design/cellar/accounts/3\nHTTP/1.1 200 OK\nContent-Length: 66\nContent-Type: application/vnd.goa.example.account+json; charset=utf-8\nDate: Sun, 06 Dec 2015 09:10:09 GMT\nServer: Google Frontend\nVary: Origin\n\n{\n    \"created_at\": \"\",\n    \"created_by\": \"me\",\n    \"href\": \"\",\n    \"id\": 3,\n    \"name\": \"sonoma\"\n}\n```\n\n### Running Locally\n\nAssuming a working Go setup:\n\n```bash\ngo install github.com/goadesign/goa-cellar\ngoa-cellar\n```\n\nOnce running `goa-cellar` listens on port 8081. The service serves the generated JavaScript example\nat `/ui`, open [http://localhost:8081/ui](http://localhost:8081/ui) in a browser to display it. This\nexample loads the generated JavaScript client from the service. It then calls the JavaScript client\n`ListBottle` function which makes a request to list the bottles to the service and displayes the\nresults.\n\n## Generated vs. Non Generated Code\n\nOne thing to be aware of when looking at the example is that most of it is generated code. The\n`design` package contains the DSL that describes the winecellar API. The contents of the `app`,\n`client`, `js`, `schema` and `swagger` folders are all completely generated by the\n[goagen](http://goa.design/implement/goagen.html) tool from the `design` package. The only non-generated directories are:\n* the `controllers` package, which contains the API business logic\n* the `store` package, which contains the database operations.\n* the `design` package itself, which contains the DSL the describes the API and which is used to generate the code \n\nThe generated documentation for the example API is available on\n[swagger.goa.design](http://swagger.goa.design/?url=goadesign%2Fgoa-cellar%2Fdesign).\n\n## FAQ\n\n### Why are the controllers in a \"controllers\" package instead of the default \"main\" package?\n\n`goagen` generates both `main.go` and the controller files in the main package by default. This\nexample splits the two and keeps `main.go` in the main package but moves the controller\nimplementations (`account.go` and `bottle.go`) to the `controllers` package. The files were moved\nand edited \"manually\".\n\nThis is to illustrate an important aspect of code generation in goa: `goagen` generates two types of\noutputs:\n\n- The *scaffold* is code that is produced once. It consists of `main.go`, the controller\n  files and the client `main.go`. These files are generated to help the project get started quickly\n  however they should be edited, moved, renamed etc. as needed.\n\n- The *generated* code is produced each time entirely from scratch. This is the vast majority of the\n  code that is outputed by `goagen` and the parts that change the most as the design evolves. This\n  includes the `app` package and its `test` subpackage, the swagger files and the client files.\n\nWhile it is possible to control where both the scaffold and generated code is produced (with the\n`--output` flag) it is not possible to edit the generated code. Any change made to these files will\nbe overridden next time `goagen` is invoked. This is to enforce a clean separation between generated\ncode and user code. Generated code calls the user code via explicit Go interfaces so that it's clear\nwhat needs to be done when the generated code differs as a result of changes in the design.\n\n### Where are the tests?\n\nThe `controllers` package illustrates how to write component level tests. These tests setup input\ndata, call the generated test helpers which package that data into HTTP requests and calls the\nactual controller functions. The test helpers retrieve the written responses, deserialize them,\nvalidate the generated data structures (against the validations written in the design) and\nmake them available to the tests. This makes it simple to use table driven tests that setup various\nkinds of inputs and validate the resulting responses. See the file\n[account_test.go](https://github.com/goadesign/goa-cellar/blob/master/controllers/account_test.go).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoadesign%2Fgoa-cellar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoadesign%2Fgoa-cellar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoadesign%2Fgoa-cellar/lists"}