{"id":25319775,"url":"https://github.com/jlucktay/rest-api","last_synced_at":"2025-06-23T16:41:18.521Z","repository":{"id":48444613,"uuid":"176123775","full_name":"jlucktay/rest-api","owner":"jlucktay","description":"RESTful API","archived":false,"fork":false,"pushed_at":"2024-09-03T19:50:11.000Z","size":250,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T00:37:52.654Z","etag":null,"topics":["api","go","learning-by-doing","lefthook","mage","restful","travis-ci"],"latest_commit_sha":null,"homepage":"","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/jlucktay.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":"2019-03-17T15:50:18.000Z","updated_at":"2022-08-08T15:26:10.000Z","dependencies_parsed_at":"2024-06-20T08:21:11.021Z","dependency_job_id":"b80ac4a2-1d9a-46a6-ab3f-f9e1c14e973d","html_url":"https://github.com/jlucktay/rest-api","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/jlucktay%2Frest-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlucktay%2Frest-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlucktay%2Frest-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlucktay%2Frest-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlucktay","download_url":"https://codeload.github.com/jlucktay/rest-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247716020,"owners_count":20984155,"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","go","learning-by-doing","lefthook","mage","restful","travis-ci"],"created_at":"2025-02-13T20:55:05.939Z","updated_at":"2025-04-07T19:32:22.010Z","avatar_url":"https://github.com/jlucktay.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jlucktay's RESTful API (`jra`)\n\n[![Travis][Travis-badge]][Travis]\n[![Codecov][Codecov-badge]][Codecov]\n[![Go Report Card][Go Report Card-badge]][Go Report Card]\n[![GoDoc][GoDoc-badge]][GoDoc]\n[![License][License-badge]][License]\n\n## Description\n\nThis is my implementation of a RESTful HTTP API capable of CRUD operations and persisting resource state to a database.\n\n### Implementation guidelines\n\n- Follow best practices, for example TDD/BDD, with a focus on full-stack testing.\n- Prioritize correctness, robustness, and extensibility over extra features and optimizations.\n- Write code with the quality bar one would expect to see in production.\n- Try to simplify by using open source frameworks and libraries where possible.\n\n## Installation\n\n### Prerequisites\n\nYou should have a [working Go environment](https://golang.org/doc/install) and have `$GOPATH/bin` in your `$PATH`.\nMage is being used for various build/run/test tasks, and should also [be installed](https://magefile.org).\n\n### Compiling\n\nTo download the source, compile, and install the relevant binaries, run:\n\n``` shell\ngo get go.jlucktay.dev/rest-api/...\n```\n\nThe source code will be located in `$GOPATH/src/go.jlucktay.dev/rest-api`.\n\nNewly compiled `jra` and `jrams` binaries will be in `$GOPATH/bin/`.\n\n#### Mage\n\nThe Magefile contains targets for various tasks, which can be listed out with `mage -l`.\n\n## Usage\n\nLaunching the API server:\n\n### Running with Docker\n\n```shell\n$ docker-compose up\nStarting rest-api_web_1   ... done\nStarting rest-api_mongo_1 ... done\nAttaching to rest-api_mongo_1, rest-api_web_1\nweb_1    | Connected to MongoDB!\nweb_1    | Collection 'payments' contains 0 records.\n...\n```\n\nThe API server will be listening at \u003chttp://localhost:8080/v1/\u003e.\n\n### Running the server directly\n\n``` shell\n$ jra\nConnected to MongoDB!\nCollection 'payments' contains 0 records.\n```\n\nSeeding the server with some sample records:\n\n``` shell\n$ jrams\nContinuing will delete ALL payment records in MongoDB (database: rest-api, collection: payments)\nPress 'Enter' to continue, or CTRL+C to cancel...\nConnected to MongoDB!\nCollection 'payments' contains 14 records.\nCollection 'payments' dropped.\nDisconnected from MongoDB.\nConnected to MongoDB!\nCollection 'payments' contains 0 records.\nAdded payment with ID '4ee3a8d8-ca7b-4290-a52c-dd5b6165ec43'.\n...\n```\n\nAccessing the server:\n\n``` shell\n$ curl --silent --request GET http://localhost:8080/v1/payments\n{\n  \"data\": [\n    {\n      \"attributes\": {\n...\n```\n\n### Documentation\n\nHere is [the full design doc] for this API, which describes the various endpoints, how to call them, and what to expect\nin return.\n\n## Testing\n\nThere is a Mage target to run tests across all packages in the repo:\n\n``` shell\n$ mage test\n?       go.jlucktay.dev/rest-api/cmd/jra    [no test files]\n?       go.jlucktay.dev/rest-api/internal/cmd/jrams [no test files]\n?       go.jlucktay.dev/rest-api/pkg/org    [no test files]\nok      go.jlucktay.dev/rest-api/pkg/server 0.187s\nok      go.jlucktay.dev/rest-api/pkg/storage        0.262s\n?       go.jlucktay.dev/rest-api/pkg/storage/inmemory       [no test files]\n?       go.jlucktay.dev/rest-api/pkg/storage/mongo  [no test files]\nok      go.jlucktay.dev/rest-api/test       0.128s\n```\n\nFor more details on how Go itself discovers and executes tests, and the various flags with which to alter behaviour\nwhen doing so, run `go help test` and `go help testflag`.\n\n## Roadmap\n\nFeatures and functionality yet to be implemented are captured in [the TODO markdown file in this repo](./docs/TODO.md)\nas well as on [the Trello board].\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n\n[Codecov-badge]: https://codecov.io/gh/jlucktay/rest-api/branch/main/graph/badge.svg\n[Codecov]: https://codecov.io/gh/jlucktay/rest-api\n\n[Go Report Card-badge]: https://goreportcard.com/badge/go.jlucktay.dev/rest-api\n[Go Report Card]: https://goreportcard.com/report/go.jlucktay.dev/rest-api\n\n[GoDoc-badge]: https://godoc.org/github.com/jlucktay/rest-api?status.svg\n[GoDoc]: https://godoc.org/github.com/jlucktay/rest-api\n\n[License-badge]: https://img.shields.io/github/license/jlucktay/rest-api.svg\n[License]: https://github.com/jlucktay/rest-api/blob/main/LICENSE\n\n[Travis-badge]: https://travis-ci.org/jlucktay/rest-api.svg?branch=main\n[Travis]: https://travis-ci.org/jlucktay/rest-api\n\n[the full design doc]: https://docs.google.com/document/d/1xtqwQDhdwTe3BUEyf3lGWycPIvl66uxDdJgHLqa9hz4\n[the Trello board]: https://trello.com/b/e4ZeAJp4\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlucktay%2Frest-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlucktay%2Frest-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlucktay%2Frest-api/lists"}