{"id":15441406,"url":"https://github.com/steveoro/goggles_api","last_synced_at":"2025-04-19T19:42:10.474Z","repository":{"id":40007484,"uuid":"52165485","full_name":"steveoro/goggles_api","owner":"steveoro","description":"API Server for Goggles 7+","archived":false,"fork":false,"pushed_at":"2024-10-23T15:28:02.000Z","size":1187,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-23T16:55:06.671Z","etag":null,"topics":["api-server","docker-container","goggles","goggles-api","rails6","sports","swimming"],"latest_commit_sha":null,"homepage":"http://master-goggles.org/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steveoro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":null,"patreon":null,"open_collective":"master-goggles","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://paypal.me/StefanoAlloro"]}},"created_at":"2016-02-20T17:21:35.000Z","updated_at":"2024-09-19T12:59:53.000Z","dependencies_parsed_at":"2024-03-27T19:28:42.797Z","dependency_job_id":"e509e185-04a6-4b2e-b0f3-60e04c055d58","html_url":"https://github.com/steveoro/goggles_api","commit_stats":{"total_commits":293,"total_committers":5,"mean_commits":58.6,"dds":0.04436860068259385,"last_synced_commit":"2be2c1051f4e6c1fa0b8f4f8bd280a863dba44e5"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveoro%2Fgoggles_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveoro%2Fgoggles_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveoro%2Fgoggles_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveoro%2Fgoggles_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steveoro","download_url":"https://codeload.github.com/steveoro/goggles_api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232548605,"owners_count":18540145,"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-server","docker-container","goggles","goggles-api","rails6","sports","swimming"],"created_at":"2024-10-01T19:20:23.794Z","updated_at":"2025-01-05T04:55:00.900Z","avatar_url":"https://github.com/steveoro.png","language":"Ruby","funding_links":["https://opencollective.com/master-goggles","https://paypal.me/StefanoAlloro"],"categories":[],"sub_categories":[],"readme":"# Goggles API README\n\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/steveoro/goggles_api/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/steveoro/goggles_api/tree/master)\n[![Maintainability](https://api.codeclimate.com/v1/badges/ffc7f57dfb4ce9d73056/maintainability)](https://codeclimate.com/github/steveoro/goggles_api/maintainability)\n[![codecov](https://codecov.io/gh/steveoro/goggles_api/branch/master/graph/badge.svg?token=A5WG7PJ9HF)](https://codecov.io/gh/steveoro/goggles_api)\n[![Coverage Status](https://coveralls.io/repos/github/steveoro/goggles_api/badge.svg?branch=master)](https://coveralls.io/github/steveoro/goggles_api?branch=master)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fsteveoro%2Fgoggles_api.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fsteveoro%2Fgoggles_api?ref=badge_shield)\n\nWraps all main Goggles' API endpoints in a stand-alone application.\n\nThe endpoints allow an authorized account to manage most DB entities as they are defined in the DB structure, returning usually a composed result that includes all first-level associations and look-up entities as well.\n\n\n\n## Wiki \u0026 HOW-TOs\n\n- [Official Framework Wiki :link:](https://github.com/steveoro/goggles_db/wiki) (v. 7+)\n\n\n## Requires\n\n- Ruby 3.1.4\n- Rails 6.0.6.1+\n- MariaDb 10.6.12+ or any other MySql equivalent version\n\n\n\n## API documentation\n\nThe official API documentation is in API Blueprint format and stored directly on this repository, under `/blueprint`.\n\nThe main index is `api_main.apib` stored in the project root while all its sibling pages are inside the aforementioned `/blueprint` folder.\n\nTo easily browse the documents while working on them, we recommend the usage of Visual Studio Code with the API Blueprint Viewer extension installed, since generating a new single static document each time is definitely cumbersome.\n\n\n### Suggested tools\n\n*IDE:*\n\n- VisualStudio Code with at least the following extensions:\n  - API Blueprint syntax highlighter\n  - API Blueprint Viewer\n  - any JSON prettyfier\n  - `html2haml` gem together with its VSCode extension\n  - any other relevant \u0026 VSCode-suggested extension (Ruby, Rails, MariaDB/MySQL \u0026 Docker for once)\n\n- Hercule, for managing the API document split among multiple files. Install it globally with:\n\n     ```bash\n     $\u003e sudo npm install -g hercule\n     ```\n\nUsing Atom as favorite IDE may work too although, last time we checked, the available API Blueprint plugin was showing more issues than the one in VSCode.\n\n\n\n## Source dependencies \u0026 how to update `GogglesDb`\n\n- [GogglesDb base engine](https://github.com/steveoro/goggles_db), core 7+\n- [JWT](https://github.com/jwt/ruby-jwt) for session handling\n- [Grape gem](https://github.com/ruby-grape/grape) for API definition\n\nYou will need to install the GogglesDb gem disabling the download of the embedded test dump with:\n\n```bash\n$\u003e GIT_LFS_SKIP_SMUDGE=1 bundle install\n```\n\nUse the same parameter _when updating the gem_ with `bundle update goggles_db` or just run the dedicated script:\n\n```bash\n$\u003e ./update_engine.sh\n```\n\nObtain a valid anonymized test DB dump image by cloning [`goggles_db`](https://github.com/steveoro/goggles_db) repo on localhost and run from the its project root:\n\n```bash\n$\u003e cd goggles_db\n$\u003e RAILS_ENV=test rails app:db:rebuild\n```\n\nCheck out [Database setup](https://github.com/steveoro/goggles_db#database-setup) on GogglesDb project's README for more info.\n\n\n\n## Configuration\n\nAll framework app projects (except for the mountable engines) handle multiple configurations for execution, development \u0026 deployment.\n\nYou can use each project of the suite:\n\n- as full-blown local installations (by cloning the source repos on localhost)\n- as a single service composed from individual containers (either by rebuilding the individual containers from scratch or by pulling the images from their DockerHub repository)\n- in any other mixed way, be it the application running on localhost while accessing the DB inside a container or vice-versa.\n\nCheck out also the WiKi about [repository credentials: management and creation](https://github.com/steveoro/goggles_db/wiki/HOWTO-dev-Goggles_credentials).\n\n\n\n### *Full Localhost* usage\n\nYou'll need a MariaDb running server \u0026 client w/ `dev` libraries (tested \u0026 recommended); alternatively, an up-to-date MySQL installation.\n\nClone the repository on localhost and use it as you would with a normal Rails application.\n\nIn order to start development, you'll need to:\n\n- create new API credentials or obtain a valid `config/master.key` for the default `credentials` file (see [Wiki](https://github.com/steveoro/goggles_db/wiki/HOWTO-dev-Goggles_credentials) about this);\n- customize `config/database.yml.example` according to your local MySQL installation and save it as `config/database.yml`;\n- customize `.env.example` (as above) and save it as `.env` in case you want to build the Docker containers;\n- obtain a a valid compressed development or test seed (`.sql.bz2`) stored under `db/dump` (see [Database setup](https://github.com/steveoro/goggles_db#database-setup)).\n\n\n### *Composed Container* usage\n\nFor usage as a composed Docker container service you won't need an actual installation of MySQL or MariaDB at all, although a client `mysql` installation is recommended in case you want to run SQL commands into the DB container from the localhost shell.\n\nIf you're using the orchestrated container service, just choose a random password for the database in the `.env` file before building the containers and follow the WiKi How-To:\n\n- [Docker usage with GogglesAPI as reference example](https://github.com/steveoro/goggles_db/wiki/HOWTO-dev-docker_usage_for_GogglesApi)\n\n\n### *Mixed cases* usage\n\nRefer to: [Setup as individual Docker containers](https://github.com/steveoro/goggles_db/wiki/HOWTO-dev-docker_usage_for_GogglesApi#setup-as-individual-docker-containers)\n\nThe `Dockerfile`s \u0026 `docker-compose` YML files work with some assumptions throughout the framework about published ports between containers and the host which is running Docker.\n\nFor instance, by changing just the current Database port in your customized `database.yml` you could switch from a typical localhost MySQL install (port 3306 running on socket) to a containerized MySQL Database on the different port published on the service (port 33060 using IP protocol).\n\n\n| Service | Default internal port | Default published port |\n|---|---|---|\n|  | _\"inside\" containers_ | _\"outside\" service_ |\nDatabase (MariaDB/MySQL) | `localhost:3306` | `33060`\nWeb app | `localhost:3000` | `8081`\n\nThe current `staging` environment configuration is an example of the app running _locally_ while connecting to the `goggles-db` container service on `localhost:33060`. (See the dedicated paragraph below.)\n\n\n\n## Audit log\n\nThe API service stores an API Audit log inside `log/api_audit.log`.\n\nThe Logger instance will split it and keep the latest 10 files of 1 MB each.\n\nAt the same time, each API call will update a dedicated entry in the `api_daily_uses` table, which can be used to compute crude usage stats on a daily basis.\n\n\n\n## How to run the test suite\n\n\n### A. Everything on _localhost_\n\nFor local testing, just keep your friend [Guard](https://github.com/guard/guard) running in the background, in a dedicated console:\n\n```bash\n$\u003e guard\n```\n\nIf you want to run the full test suite, just hit enter on the Guard console. Refer to the official Guard docs for more info.\n\nAs of Rails 6.0.3, most probably there are some issues with the combined usage of Guard \u0026 Spring when used together with the new memory management modes in Rails during the Brakeman checks. These prevent the `brakeman` plugin for Guard to actually notice changes in the source code:if you create a vulnerability and subsequently fix it, the checks get re-run by Guard but the result doesn't change.\n\nMaybe it could be just a combined mis-configuration we haven't investigated thoroughly but, in any case, although the Guard plugin for Brakeman runs correctly at start, it's always better to re-run the `brakeman` checks before pushing the changes to the repository with:\n\n```bash\n$\u003e brakeman -c .brakeman.cfg\n```\n\nIf you don't have a local test database setup, check out [\"Database setup\"](https://github.com/steveoro/goggles_db#database-setup).\n\n_Make sure you commit \u0026 push any changes only when the test suite is_ :green_heart:.\n\n\n### B. Everything on _Docker containers_\n\nAlthough not optimized for testing, the `dev` composed service can be used to run RSpec, Rubocop or anything else, including Guard too.\n\nRefer to the [\"GogglesAPI: Docker usage\"](https://github.com/steveoro/goggles_db/wiki/HOWTO-dev-docker_usage_for_GogglesApi#getting-started-setup-and-usage-as-a-composed-docker-service) guide for more detailed instructions.\n\nRun the composed container in detached mode, then connect to its internal shell and run the tests:\n\n```bash\n$\u003e docker-compose -f docker-compose.dev.yml up -d\n$\u003e docker-compose -f docker-compose.dev.yml exec app sh\n\n/app # RAILS_ENV=test bundle exec rspec\n\n/app # RAILS_ENV=test bundle exec rubocop\n\n/app # RAILS_ENV=test bundle exec brakeman -q\n\n/app # RAILS_ENV=test bundle exec guard\n```\n\nInside the container, remember to:\n\n- always prefix the usual commands with `bundle exec` (as in `bundle exec rails console`, ...) to reach the correct bundle (stored in `/usr/local/bundle`);\n- override the default RAILS_ENV `development` for anything test-related.\n\n\n* * *\n\n\n## Dev Workflow _(for contributors)_\n\nWhen you push a commit to the `master` branch, the build system will re-test everything you allegedly have already checked locally using [Guard](https://github.com/guard/guard) as described above.\n\nThe project uses a _full CI pipeline_ setup on Semaphore 2.0 (currently for the `master` branch only) that will promote a successful build into the Docker `latest` production-only image on DockerHub.\n\nAll other tagged Docker images will be auto-built by DockerHub itself, as soon as any specific branch has been _manually tagged_ as a _release_ from the GitHub UI. (Using GitHub release tags that respect semantic versioning, with format `MAJOR`.`MINOR`.`BUILD`)\n\nGiven this, avoid cluttering the build queue with tiny commits (unless these are hotfixes) and with something that hasn't been greenlit by a local run of the whole test suite: it's adamant that you don't push failing builds whenever possible.\n\nBasically, remember to:\n\n- login to docker from the console with `docker login` whenever you're using Docker for testing or development (in order to avoid pull/push threshold caps);\n- always develop with a running `guard` in background;\n- when you're ready to push, do a full test suite run (just to be sure);\n- run also an additional Brakeman scan before the push as suggested above.\n\n\n* * *\n\n\n## Database setup\n\nRefer to [GogglesDb setup](https://github.com/steveoro/goggles_db#database-setup).\n\nYou'll need a proper DB for both the test suite and the local development.\n\nAssuming we want the `test` environment DB up and running, you can either have:\n\n\n### A. Everything on _localhost_\n\n- Make sure you have a running MariaDB server \u0026 client installation.\n\n- Given you have a valid `db/dump/test.sql.bz2` (the dump must be un-namespaced to be copied or renamed from any other environment - as those created by `db:dump` typically are), use the dedicated rake tasks:\n\n```bash\n$\u003e bin/rails db:rebuild from=test to=test\n$\u003e RAILS_ENV=test bin/rails db:migrate\n```\n\n(It will take some time, depending of the dump size: sit back and relax.)\n\n\n### B. Using _Docker containers_\n\nRefer to [\"Getting started: setup and usage as a composed Docker service\"](https://github.com/steveoro/goggles_db/wiki/HOWTO-dev-docker_usage_for_GogglesApi#getting-started-setup-and-usage-as-a-composed-docker-service) or to [\"DB container setup \u0026 usage\"](https://github.com/steveoro/goggles_db/wiki/HOWTO-dev-docker_usage_for_GogglesApi#db-container-setup--usage-low-level-approach) for in-depth details.\n\n\n* * *\n\n\n## Staging\n\nStaging will use a custom copy of the `production` environment together with the database running on the production Docker image (tag: `latest`) of the composed service (DockerHub: `steveoro/goggles-api:latest`), minus the SSL enforcing (so that we can test that easily on localhost).\n\nTo recreate or restore a usable database with testing seeds, assuming:\n\n1. you have a valid `test.sql.bz2` dump file stored under `db/dumps`;\n2. the DB container `goggles-db` has been already built and already running;\n\nExecute the dedicated task:\n\n```bash\n$\u003e RAILS_ENV=staging rails db:rebuild from=test to=staging\n```\n\nRun the server on localhost with:\n\n```bash\n$\u003e rails s -p 8081 -e staging\n```\n\n...Or the console with:\n\n```bash\n$\u003e rails c -e staging\n```\n\n\n* * *\n\n\n## Deployment instructions\n\n:construction: TODO :construction:\n\n\n* * *\n\n\n## Contributing\n1. Clone the project.\n2. Make a new custom branch for your changes, naming the branch accordingly (i.e. use prefixes like: `feature-`, `fix-`, `upgrade-`, ...).\n3. When you think you're done, make sure you type `guard` (+`Enter`) and wait for the whole spec suite to end.\n4. Make sure your branch is locally green (:green_heart:) before submitting the pull request.\n5. Await the PR's review by the maintainers.\n\n\n## License\nThe application is available as open source under the terms of the [LGPL-3.0 License](https://opensource.org/licenses/LGPL-3.0).\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fsteveoro%2Fgoggles_api.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fsteveoro%2Fgoggles_api?ref=badge_large)\n\n\n## Supporting\n\nCheck out the \"sponsor\" button at the top of the page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteveoro%2Fgoggles_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteveoro%2Fgoggles_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteveoro%2Fgoggles_api/lists"}