{"id":13625087,"url":"https://github.com/raharrison/kotlin-ktor-exposed-starter","last_synced_at":"2025-05-15T12:05:04.637Z","repository":{"id":37548644,"uuid":"123470901","full_name":"raharrison/kotlin-ktor-exposed-starter","owner":"raharrison","description":"Starter RESTful service with websocket notifications using Kotlin, Ktor and Exposed with H2, HikariCP and FlyWay","archived":false,"fork":false,"pushed_at":"2025-03-08T16:33:59.000Z","size":220,"stargazers_count":580,"open_issues_count":5,"forks_count":77,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-14T22:18:26.338Z","etag":null,"topics":["exposed","flyway","h2-database","jackson","kotlin","kotlin-coroutines","ktor","netty","rest-api","websocket"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raharrison.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2018-03-01T17:45:04.000Z","updated_at":"2025-04-07T12:01:43.000Z","dependencies_parsed_at":"2023-02-11T17:05:27.813Z","dependency_job_id":"ff7eb3e1-fb92-446b-a375-775be9c5b6ed","html_url":"https://github.com/raharrison/kotlin-ktor-exposed-starter","commit_stats":{"total_commits":147,"total_committers":8,"mean_commits":18.375,"dds":"0.25850340136054417","last_synced_commit":"7a6233432e4b10187b3d6e12f0316f827ba5a879"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raharrison%2Fkotlin-ktor-exposed-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raharrison%2Fkotlin-ktor-exposed-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raharrison%2Fkotlin-ktor-exposed-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raharrison%2Fkotlin-ktor-exposed-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raharrison","download_url":"https://codeload.github.com/raharrison/kotlin-ktor-exposed-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337612,"owners_count":22054253,"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":["exposed","flyway","h2-database","jackson","kotlin","kotlin-coroutines","ktor","netty","rest-api","websocket"],"created_at":"2024-08-01T21:01:50.680Z","updated_at":"2025-05-15T12:04:59.618Z","avatar_url":"https://github.com/raharrison.png","language":"Kotlin","funding_links":[],"categories":["Educational Projects","Kotlin","企业软件开发"],"sub_categories":["Episodes","文件同步"],"readme":"[![Kotlin](https://img.shields.io/badge/kotlin-2.0.21-blue.svg?logo=kotlin)](http://kotlinlang.org)\n[![Ktor](https://img.shields.io/badge/ktor-3.0.0-blue.svg)](https://github.com/ktorio/ktor)\n[![Build](https://github.com/raharrison/kotlin-ktor-exposed-starter/workflows/Build/badge.svg)](https://github.com/raharrison/kotlin-ktor-exposed-starter/actions/workflows/build.yml)\n[![codecov](https://codecov.io/gh/raharrison/kotlin-ktor-exposed-starter/branch/master/graph/badge.svg?token=v2k9oObm0C)](https://codecov.io/gh/raharrison/kotlin-ktor-exposed-starter)\n\n## Starter project to create a simple RESTful web service in Kotlin\n\n**Updated for Kotlin 2.1.10 and Ktor 3.1.1**\n\nCompanion article: \u003chttps://ryanharrison.co.uk/2018/04/14/kotlin-ktor-exposed-starter.html\u003e\n\n## Getting Started\n\n1. Clone the repo.\n2. In the root directory execute `./gradlew run`\n3. By default, the server will start on port `8080`. See below [Routes](#routes) section for more information.\n\n### Libraries used:\n\n - [Ktor](https://github.com/ktorio/ktor) - Kotlin async web framework\n - [Netty](https://github.com/netty/netty) - Async web server\n - [Kotlin Serialization](https://github.com/Kotlin/kotlinx.serialization) - JSON serialization/deserialization\n - [Exposed](https://github.com/JetBrains/Exposed) - Kotlin SQL framework\n - [H2](https://github.com/h2database/h2database) - Embeddable database\n - [HikariCP](https://github.com/brettwooldridge/HikariCP) - High performance JDBC connection pooling\n - [Flyway](https://flywaydb.org/) - Database migrations\n - [JUnit 5](https://junit.org/junit5/), [AssertJ](http://joel-costigliola.github.io/assertj/)\n   and [Rest Assured](http://rest-assured.io/) for testing\n - [Kover](https://github.com/Kotlin/kotlinx-kover) for code coverage, publishing\n   to [Codecov](https://about.codecov.io/) through GitHub Actions\n \nThe starter project creates a new in-memory H2 database with one table for `Widget` instances.\n\nAs ktor is async and based on coroutines, standard blocking JDBC may cause performance issues when used\ndirectly on the main thread pool (as threads must be reused for other requests). Therefore, another dedicated thread\npool is created for all database queries, alongside connection pooling with HikariCP. \n\n### Routes:\n\n`GET /widgets` --\u003e get all widgets in the database\n\n`GET /widgets/{id}` --\u003e get one widget instance by id (integer)\n\n`POST /widgets` --\u003e add a new widget to the database by providing a JSON object (converted to a NewWidget instance). e.g - \n\n```json\n{\n    \"name\": \"new widget\",\n    \"quantity\": 64\n}\n```\n\nreturns\n\n```json\n{\n    \"id\": 3,\n    \"name\": \"new widget\",\n    \"quantity\": 64,\n    \"dateUpdated\": 1519926898\n}\n```  \n    \n`PUT /widgets` --\u003e update an existing widgets name or quantity. Pass in the id in the JSON request to determine which record to update\n\n`DELETE /widgets/{id}` --\u003e delete the widget with the specified id\n\n### Notifications (WebSocket)\n\nAll updates (creates, updates and deletes) to `Widget` instances are served as notifications through a WebSocket endpoint:\n\n`WS /updates` --\u003e returns `Notification` instances containing the change type, id and entity (if applicable) e.g:\n\n```json\n{ \n    \"type\": \"CREATE\", \n    \"id\": 12, \n    \"entity\": { \n      \"id\": 12, \n      \"name\": \"widget1\", \n      \"quantity\": 5, \n      \"dateUpdated\": 1533583858169 \n    }\n}\n```\n\nThe websocket listener will also log out any text messages send by the client. Refer to [this blog post](https://ryanharrison.co.uk/2018/08/19/testing-websockets.html) for some useful tools to test the websocket behaviour.\n\n### Testing\n\nThe sample Widget service and corresponding endpoints are also tested with 100% coverage. Upon startup of the main JUnit suite (via the `test` source folder), the server is started ready for testing and is torn down after all tests are run.\n\n- Unit testing of services with AssertJ - DAO and business logic is tested by initialising an in-memory H2 database with\n  Exposed, using the same schema as the main app. With this approach database queries are fully tested without any\n  mocking.\n- Integration testing of endpoints using a fully running server with Rest Assured - routing tests/status codes/response\n  structure. This utilises the fact that Ktor is a small microframework that can be easily spun up and down as part of\n  the test suite. You could also use the special test engine that [Ktor provides](https://ktor.io/docs/testing.html),\n  however my preference is to always start a full version of the server so that HTTP behaviour can be tested without\n  relying on special internal mechanisms.\n- Code coverage and reporting performed automatically by Kover as part of the Gradle build\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraharrison%2Fkotlin-ktor-exposed-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraharrison%2Fkotlin-ktor-exposed-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraharrison%2Fkotlin-ktor-exposed-starter/lists"}