{"id":21372388,"url":"https://github.com/automationpanda/device-registry-fastapi","last_synced_at":"2025-07-13T07:32:07.118Z","repository":{"id":64848980,"uuid":"578851503","full_name":"AutomationPanda/device-registry-fastapi","owner":"AutomationPanda","description":"An example REST API web service for registering smart devices, written in Python using FastAPI","archived":false,"fork":false,"pushed_at":"2023-02-04T22:08:34.000Z","size":89,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-04-28T03:37:41.535Z","etag":null,"topics":["example","fastapi","pytest","python","python-testing","requests","rest","rest-api","rest-api-tests","test-automation","testing","the-way-to-test-software"],"latest_commit_sha":null,"homepage":"","language":"Python","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/AutomationPanda.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":"2022-12-16T03:02:37.000Z","updated_at":"2024-04-18T05:08:36.000Z","dependencies_parsed_at":"2023-02-18T19:46:12.244Z","dependency_job_id":null,"html_url":"https://github.com/AutomationPanda/device-registry-fastapi","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/AutomationPanda%2Fdevice-registry-fastapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AutomationPanda%2Fdevice-registry-fastapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AutomationPanda%2Fdevice-registry-fastapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AutomationPanda%2Fdevice-registry-fastapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AutomationPanda","download_url":"https://codeload.github.com/AutomationPanda/device-registry-fastapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225863855,"owners_count":17536177,"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":["example","fastapi","pytest","python","python-testing","requests","rest","rest-api","rest-api-tests","test-automation","testing","the-way-to-test-software"],"created_at":"2024-11-22T08:19:29.291Z","updated_at":"2024-11-22T08:19:29.767Z","avatar_url":"https://github.com/AutomationPanda.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Device Registry Service (FastAPI)\n\nThis repository contains the **Device Registry Service**,\nan example REST API web service for registering smart devices.\nIt is written in Python using [FastAPI](https://fastapi.tiangolo.com/),\nand it stores data in a [TinyDB](https://tinydb.readthedocs.io/en/latest/) database (as a JSON file).\nNote that it is not a \"real\" web service, but rather one to use as a teaching example.\nThis project also contains integration tests to test the REST API endpoints.\n\nWhat does the Device Registry Service do?\nIt stores records for all smart devices a user owns in one central place.\nA home could have multiple kinds of smart devices:\nWiFi routers, voice assistants, thermostats, light switches, and even appliances.\nThis service stores information like name, location, type, model, and serial number for each device.\nIts API enables callers to practice CRUD (Create, Retrieve, Update, Delete) operations.\nIn theory, a dashboard or monitoring app could use a registry service like this to quickly access devices.\n\n*Note:*\nThis repository is the example project for Chapters 6 and 7 in Andrew Knight's book, *The Way To Test Software*.\n\n\n## Installation\n\nThe Device Registry Service is designed to run on your local machine.\nIt should run on any operating system (Windows, macOS, Linux).\nTo install it:\n\n1. Install [Python](https://www.python.org/) 3.8 or higher.\n2. Clone the GitHub repository on to your local machine.\n3. Install dependency packages from the command line:\n   1. Change directory to the project's root directory.\n   2. Run `pip install -r requirements.txt` to install all dependencies.\n\n\n## Running the web service\n\nThe Device Registry Service is written using [FastAPI](https://fastapi.tiangolo.com/).\nTo run the web service (or \"app\"), run the following command:\n\n```\nuvicorn app.main:app\n```\n\nYou should see output like this from the command line:\n\n```bash\nINFO:     Started server process [8846]\nINFO:     Waiting for application startup.\nINFO:     Application startup complete.\nINFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)\n```\n\nWhen running, the web service can be accessed at `http://127.0.0.1:8000/`\n(the address printed in the command's output).\nIf you load that address in a web browser, you should see docs for the REST API.\n\n*Note:*\nRun `uvicorn app.main:app --reload` to automatically refresh the app whenever its code is changed.\n\nYou can kill the app by typing Ctrl-C.\n\n\n## Choosing a database\n\nThe Device Registry Service uses a [TinyDB](https://tinydb.readthedocs.io/en/latest/) database.\nTinyDB is not meant to be a high-scale production database,\nbut it works just fine for this small example app.\n\nTinyDB databases are stored as JSON files.\nThis repository comes with two TinyDB databases:\n\n1. [`registry-dev.json`](registry-dev.json)\n    * A *dev* database prepopulated with a few devices.\n    * Use this one when manually poking around the app.\n2. [`registry-test.json`](registry-test.json)\n   * A *test* database that is empty from the start.\n   * Use this one when running integration tests.\n\nYou can choose which database to use by setting the `database` property in [`config.json`](config.json).\n(Read more about setting configuration options in the next section.)\nThe configuration defaults to the *test* database.\nYou can always discard local changes (`git restore`) to the database files to reset them.\n\n\n## Configuring the web service\n\nThe Device Registry Service stores all its configuration options in [`config.json`](config.json).\nThe following configurations must be set in this file:\n\n* `users`: an object of valid usernames and passwords for authentication\n* `databases`: an object of available database names and their file paths\n* `database`: the key for the database to use from the `databases` object\n* `secret_key`: a secret key for generating JWT authentication tokens\n\nIt is recommended to use the `config.json` values provided by the repository.\nHowever, you may change these values for added security or customization.\n\n*Warning:*\nTypically, a configuration file with secrets like these should **not** be committed to source control.\nHowever, since this is an example project, it is committed with code for convenience.\n\n\n## Reading the REST API docs\n\nThe Device Registry Service's APIs conform to the [OpenAPI Specification](https://www.openapis.org/).\nFastAPI automatically generates docs at the following resource paths:\n\n* `/docs`: The classic [Swagger UI](https://github.com/swagger-api/swagger-ui) docs\n* `/redoc`: The more modern [Redoc](https://github.com/Redocly/redoc) docs\n\nYou can use these doc pages to learn how to call each endpoint.\nYou can also test the endpoints through the Swagger UI docs (`/docs`).\n\n*Note:*\nThe home page (`/`) will redirect to the `/docs` page.\n\n\n## Configuring the test cases\n\nREST API integration tests are located in the `tests` directory.\nThey are written using [pytest](https://docs.pytest.org/).\nThe tests are not unit tests - they send requests to a live version of the Device Registry Service.\nIf you try to run them without the following setup steps, they will fail.\n\nThe tests require a configuration file that specifies the app's base URL and available users.\nThis file is located at [`tests/integration/inputs.json`](tests/integration/inputs.json).\nIt is a *separate* configuration file from the app's [`config.json`](config.json) file.\nThe following configurations must be set in this file:\n\n* `base_url`: the base URL for the app under test\n* `users`: a list of objects providing `username` and `password` values\n\nThese values should mirror the ones for the instance of the app under test.\nThe values provided out-of-the-box from the repository should work.\n\n*Warning:*\nAgain, a configuration file like this should **not** be committed to source control.\nHowever, since this is an example project, it is committed with code for convenience.\n\n\n## Running the test cases\n\nOnce the inputs file is ready, configure the app to use the `test` database and run it.\nThen, in another command line terminal, run `python -m pytest tests`.\nNote that the app must be running *before* launching the tests.\n\nHere's a condensed guide for running tests:\n\n1. In `config.json`, set the `database` value to `test`.\n2. Run `uvicorn app.main:app` from the project root directory.\n3. Separately run `python -m pytest tests` from the project root directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautomationpanda%2Fdevice-registry-fastapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fautomationpanda%2Fdevice-registry-fastapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fautomationpanda%2Fdevice-registry-fastapi/lists"}