As developers, we deal with REST APIs on daily basis, as mobile/frontend developers, to consume these APIs and as Backend developers to develop these APIs. As an Android dev, I was always curious about backend technologies and how this API related stuff works under the hood. And I am sure this holds true for most frontend as well as Android/iOS devs. But now the important question for me now was how to choose the right backend technology for your app. Being an Android dev, I was quite familiar with Kotlin, and when I learnt about Ktor I straight away started with the same, and the developing experience has been amazing so far.
Ktor is a framework to easily build connected applications — web applications, HTTP services, mobile and browser applications.
Let’s quickly get started and develop basic notes API with CRUD operations in Ktor!
Endpoints
The API endpoints for our notes API will be -:
1. Create a new note
POST http://0.0.0.0:3536/notes
2. Fetch all notes
GET http://0.0.0.0:3536/notes
3. Fetch a particular note
GET http://0.0.0.0:3536/notes/{id}
4. Delete a particular note
DELETE http://0.0.0.0:3536/notes/{id}
5. Update a particular note
PUT http://0.0.0.0:3536/notes/{id}
Database
After doing some research on databases, I chose Ktorm.
Ktorm is a lightweight and efficient ORM Framework for Kotlin directly based on pure JDBC. It provides strong-typed and flexible SQL DSL and convenient sequence APIs to reduce our duplicated effort on database operations.
The fact that this ORM framework provides DSL support for SQL queries encouraged me to pick it up. Kotlin gives you the tools to help craft code into something which feels more natural to use, through DSL, and DSL support for SQL queries, definitely helps us write more clean and understandable code. The development time also reduces a lot as writing raw SQL queries may require some time and efforts, especially for non-backend developers. Ktorm generates raw SQL queries for you under the hood.
Ktorm Query to Insert into Database :
| database.insert(Notes) { | |
| set(it.id, "id") | |
| set(it.note, "note") | |
| } |
Generated SQL:
| insert into t_note (id,note) values (?, ?) |
Job Offers
OUR VIDEO RECOMMENDATION
Jobs
Routing
Routing is one of the most important aspects to be token into consideration when developing REST APIs. Routing defines the endpoints of our APIs. How our API knows which action to perform on which URL or various endpoints is through Routing. Ktor provides a convenient way of Routing using the Routing Plugin provided by Ktor framework. Here is the representation of the fetch notes API endpoint. We will place this in our main function of Application.kt file.
| routing { | |
| get("/notes") { | |
| val notes = arraylistof("Note 1","Note 2") | |
| call.respond(notes) | |
| } | |
| } |
Request and Response
While dealing with REST APIs, we deal with parameters, headers, auth , request body, response body etc. I assume you understand the basics of the same. In case you’re not familiar with all these terminologies, I urge you to read about the same and then switch back to current article.In this article we will only discuss about how to deal with Request and Response bodies in Ktor.
1. Request Body
a) Create a Request Model Class which represents a Request Body of our Create Notes API:
| @Serializable | |
| data class NoteRequest(val note: String) |
b) Get the Request Body parameters in the Routing Function:
| val request = call.receive<NoteRequest>() | |
| val result = db.insert(NotesEntity) { | |
| set(it.note, request.note) | |
| } |
2. Response Body
a) Create a Response Model Class which represents a Response Body of our Fetch Notes API:
| @Serializable | |
| data class NoteResponse<T>( | |
| val data: T, | |
| val success: Boolean | |
| ) |
b) Handle returning the response body on API call by the client.
| get("/notes") { | |
| val notes = db.from(NotesResponse).select().map { | |
| val id = it[NotesEntity.id] | |
| val note = it[NotesEntity.note] | |
| Note(id ?: -1, note ?: "") | |
| } | |
| // Returns the response to the User | |
| call.respond(notes) | |
| } |
Connecting the dots
We are now ready to connect the dots and complete our project. Yayy!
I will list the relevant code as per the scope of the article.In case you want to display the whole project, please check the source code mentioned at the end of the article.
Code for NotesRoute.kt:
| fun Application.notesRoutes() { | |
| val db = DatabaseConnection.database | |
| routing { | |
| get("/notes") { | |
| val notes = db.from(NotesEntity).select().map { | |
| val id = it[NotesEntity.id] | |
| val note = it[NotesEntity.note] | |
| Note(id ?: -1, note ?: "") | |
| } | |
| call.respond(notes) | |
| } | |
| post("/notes") { | |
| val request = call.receive<NoteRequest>() | |
| val result = db.insert(NotesEntity) { | |
| set(it.note, request.note) | |
| } | |
| // Verify only 1 row has been inserted | |
| if (result == 1) { | |
| // To Successful response to the client | |
| call.respond( | |
| HttpStatusCode.OK, | |
| NoteResponse( | |
| success = true, | |
| data = "Value has been successfully inserted" | |
| ) | |
| ) | |
| } else { | |
| // Send Failure response to the client | |
| call.respond( | |
| HttpStatusCode.BadRequest, | |
| NoteResponse( | |
| success = false, | |
| data = "Failed to Insert Value" | |
| ) | |
| ) | |
| } | |
| } | |
| get("/notes/{id}") { | |
| val id: Int = call.parameters["id"]?.toInt() ?: -1 | |
| val note = db.from(NotesEntity) | |
| .select() | |
| .where { NotesEntity.id eq id } | |
| .map { | |
| val note = it[NotesEntity.note]!! | |
| Note(id = id, note = note) | |
| }.firstOrNull() | |
| if (note == null) { | |
| call.respond( | |
| HttpStatusCode.NotFound, | |
| NoteResponse(success = false, data = "Could not find note with that id = $id") | |
| ) | |
| } else { | |
| call.respond( | |
| HttpStatusCode.OK, | |
| NoteResponse(success = true, data = note) | |
| ) | |
| } | |
| } | |
| put("/notes/{id}") { | |
| val id = call.parameters["id"]?.toInt() ?: -1 | |
| val updatedNote = call.receive<NoteRequest>() | |
| val rowsEffected = db.update(NotesEntity) { | |
| set(it.note, updatedNote.note) | |
| where { | |
| it.id eq id | |
| } | |
| } | |
| if (rowsEffected != 1) { | |
| call.respond( | |
| HttpStatusCode.NotFound, | |
| NoteResponse(success = false, data = "Could not find note with that id = $id") | |
| ) | |
| } else { | |
| call.respond( | |
| HttpStatusCode.OK, | |
| NoteResponse(success = true, data = "Success") | |
| ) | |
| } | |
| } | |
| delete("/notes/{id}") { | |
| val id: Int = call.parameters["id"]?.toInt() ?: -1 | |
| val rowsEffected = db.delete(NotesEntity) { | |
| it.id eq id | |
| } | |
| if (rowsEffected != 1) { | |
| call.respond( | |
| HttpStatusCode.NotFound, | |
| NoteResponse(success = false, data = "Could not find note with that id = $id") | |
| ) | |
| } else { | |
| call.respond( | |
| HttpStatusCode.OK, | |
| NoteResponse(success = true, data = "Success") | |
| ) | |
| } | |
| } | |
| } | |
| } |
For complete code, check out the repo ktor-api
Thanks for your patience, will be back soon with a new article related to Ktor and continue the project. Stay tuned.
