Para agentes de IA: hay un Ć­ndice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las pĆ”ginas estĆ”n disponibles agregando .md a cualquier ruta URL.

Crea una API utilizando Ktor y MongoDB Atlas

Ktor es un framework web asíncrono basado en Kotlin diseñado para crear aplicaciones web modernas y APIs. Ofrece un sólido soporte para la programación asincrónica con rutinas de Kotlin.

En este tutorial, aprenderÔs cómo configurar un API ejecutable utilizando Ktor, el controlador de Kotlin y MongoDB Atlas.

1

Antes de comenzar este tutorial, asegĆŗrate de tener lo siguiente:

2

Crea un nuevo proyecto de Ktor utilizando el Generador de proyectos de Ktor. Asigne un nombre al artefacto del proyecto com.mongodb.fitness-tracker utilizando el campo de entrada de texto. Haga clic en el botón Configure y especifique las siguientes opciones:

  • Sistema de compilación: Gradle Kotlin

  • Motor: Tomcat

  • Configuración: Archivo HOCON

Utilizando el menú Plugins en la pÔgina del Nuevo Proyecto Ktor, añade los siguientes complementos a tu proyecto:

  • Negociación de contenido: Negocia los tipos de medios entre el cliente y el servidor

  • GSON: Brinda soporte para serialización y deserialization

  • Enrutamiento: gestiona las solicitudes entrantes

  • Swagger: Genera documentación de API

Haz clic en el botón Generate Project para descargar un archivo ZIP que contiene tu nuevo proyecto Ktor.

Descomprime el archivo descargado y abre el archivo build.gradle.kts en el directorio raƭz del Proyecto. AƱade los siguientes plugins al bloque plugins:

plugins { kotlin("jvm") version "1.9.22" id("io.ktor.plugin") version "2.3.7" id("org.jetbrains.kotlin.plugin.serialization") version "1.9.22"}

Agregue las siguientes dependencias al bloque dependencies en el mismo archivo:

dependencies { implementation("io.ktor:ktor-server-core-jvm") implementation("io.ktor:ktor-server-swagger-jvm") implementation("io.ktor:ktor-server-content-negotiation-jvm") implementation("io.ktor:ktor-serialization-gson-jvm") implementation("io.ktor:ktor-server-tomcat-jvm") implementation("ch.qos.logback:logback-classic:$logback_version") implementation("io.ktor:ktor-server-config-yaml:2.3.8") // MongoDB implementation("org.mongodb:mongodb-driver-kotlin-coroutine:5.14.0") // Koin dependency injection implementation("io.insert-koin:koin-ktor:3.5.3") implementation("io.insert-koin:koin-logger-slf4j:3.5.3") // Client implementation("io.ktor:ktor-client-core:$ktor_version") implementation("io.ktor:ktor-client-cio:$ktor_version")}
3

Crea los siguientes tres paquetes bajo el directorio src/main/kotlin:

  • application

  • domain

  • infrastructure

Dentro del paquete domain, crea un nuevo subpaquete llamado entity, luego crea un archivo dentro de entity llamado Fitness.kt. Copia el siguiente código en el archivo:

package com.mongodb.domain.entityimport com.mongodb.application.response.FitnessResponseimport org.bson.codecs.pojo.annotations.BsonIdimport org.bson.types.ObjectId data class Fitness( @BsonId val id: ObjectId, val exerciseType: String, val notes: String, val details: FitnessDetails){ fun toResponse() = FitnessResponse( id = id.toString(), exerciseType = exerciseType, notes = notes, details = details )} data class FitnessDetails( val durationMinutes: Int, val distance: Double, val caloriesBurned: Int)

El método toResponse() en el código anterior arroja un error porque aún no has creado la clase FitnessResponse. Crea paquetes request y response debajo del paquete application/request y crea dos archivos llamados FitnessRequest.kt y FitnessResponse.kt en el paquete correspondiente.

Copia el siguiente código en el archivo FitnessRequest.kt:

package com.mongodb.application.response import com.mongodb.domain.entity.FitnessDetails data class FitnessResponse( val id: String, val exerciseType: String, val notes: String, val details: FitnessDetails)

Copia el siguiente código en el archivo FitnessResponse.kt:

package com.mongodb.application.response import com.mongodb.domain.entity.FitnessDetails data class FitnessResponse( val id: String, val exerciseType: String, val notes: String, val details: FitnessDetails)

Crear un paquete ports bajo el paquete domain y crear un archivo llamado FitnessRepository.kt en el paquete ports. Este archivo representa la interfaz que se comunicarÔ con la base de datos. Copie el siguiente código en el archivo FitnessRepository.kt:

package com.mongodb.domain.ports import com.mongodb.domain.entity.Fitnessimport org.bson.BsonValueimport org.bson.types.ObjectId interface FitnessRepository { suspend fun insertOne(fitness: Fitness): BsonValue? suspend fun deleteById(objectId: ObjectId): Long suspend fun findById(objectId: ObjectId): Fitness? suspend fun updateOne(objectId: ObjectId, fitness: Fitness): Long}

Crea un paquete repository dentro del paquete infrastructure y crea un archivo llamado FitnessRepositoryImpl.kt en el paquete repository. Este archivo implementa los métodos de la interfaz. Copie el siguiente código en el archivo FitnessRepositoryImpl.kt:

package com.mongodb.infrastructure.repository import com.mongodb.MongoExceptionimport com.mongodb.client.model.Filtersimport com.mongodb.client.model.UpdateOptionsimport com.mongodb.client.model.Updatesimport com.mongodb.domain.entity.Fitnessimport com.mongodb.domain.ports.FitnessRepositoryimport com.mongodb.kotlin.client.coroutine.MongoDatabaseimport kotlinx.coroutines.flow.firstOrNullimport org.bson.BsonValueimport org.bson.types.ObjectId class FitnessRepositoryImpl( private val mongoDatabase: MongoDatabase) : FitnessRepository { companion object { const val FITNESS_COLLECTION = "fitness" } override suspend fun insertOne(fitness: Fitness): BsonValue? { try { val result = mongoDatabase.getCollection<Fitness>(FITNESS_COLLECTION).insertOne( fitness ) return result.insertedId } catch (e: MongoException) { System.err.println("Unable to insert due to an error: $e") } return null } override suspend fun deleteById(objectId: ObjectId): Long { try { val result = mongoDatabase.getCollection<Fitness>(FITNESS_COLLECTION).deleteOne(Filters.eq("_id", objectId)) return result.deletedCount } catch (e: MongoException) { System.err.println("Unable to delete due to an error: $e") } return 0 } override suspend fun findById(objectId: ObjectId): Fitness? = mongoDatabase.getCollection<Fitness>(FITNESS_COLLECTION).withDocumentClass<Fitness>() .find(Filters.eq("_id", objectId)) .firstOrNull() override suspend fun updateOne(objectId: ObjectId, fitness: Fitness): Long { try { val query = Filters.eq("_id", objectId) val updates = Updates.combine( Updates.set(Fitness::exerciseType.name, fitness.exerciseType), Updates.set(Fitness::notes.name, fitness.notes), Updates.set(Fitness::details.name, fitness.details) ) val options = UpdateOptions().upsert(true) val result = mongoDatabase.getCollection<Fitness>(FITNESS_COLLECTION) .updateOne(query, updates, options) return result.modifiedCount } catch (e: MongoException) { System.err.println("Unable to update due to an error: $e") } return 0 }}
4

Pega el siguiente código en el archivo Application.kt. Este código realiza las siguientes acciones:

  1. Configura el complemento ContentNegotiation para gestionar la serialización y deserialización JSON utilizando el formateador Gson

  2. Permite la inyección de dependencias utilizando Koin

  3. Configura la ruta de Swagger API, que estĆ” disponible en el endpoint /swagger

package com.mongodb import com.mongodb.application.routes.fitnessRoutesimport com.mongodb.domain.ports.FitnessRepositoryimport com.mongodb.infrastructure.repository.FitnessRepositoryImplimport com.mongodb.kotlin.client.coroutine.MongoClientimport io.ktor.serialization.gson.gsonimport io.ktor.server.application.Applicationimport io.ktor.server.application.installimport io.ktor.server.plugins.contentnegotiation.ContentNegotiationimport io.ktor.server.plugins.swagger.swaggerUIimport io.ktor.server.routing.routingimport io.ktor.server.tomcat.EngineMainimport org.koin.dsl.moduleimport org.koin.ktor.plugin.Koinimport org.koin.logger.slf4jLogger fun main(args: Array<String>): Unit = EngineMain.main(args) fun Application.module() { install(ContentNegotiation) { gson { } } install(Koin) { slf4jLogger() modules(module { single { MongoClient.create( environment.config.propertyOrNull("ktor.mongo.uri")?.getString() ?: throw RuntimeException("Failed to access MongoDB URI.") ) } single { get<MongoClient>().getDatabase(environment.config.property("ktor.mongo.database").getString()) } }, module { single<FitnessRepository> { FitnessRepositoryImpl(get()) } }) } routing { swaggerUI(path = "swagger-ui", swaggerFile = "openapi/documentation.yaml") { version = "4.15.5" } fitnessRoutes() }}

Abra el archivo application.conf y pegue lo siguiente:

ktor { deployment { port = 8080 } application { modules = [ com.mongodb.ApplicationKt.module ] } mongo { uri = ${?MONGO_URI} database = ${?MONGO_DATABASE} }}

Abra el archivo documentation.yaml y pegue lo siguiente:

openapi: 3.0.0info: title: Fitness API version: 1.0.0 description: | This Swagger documentation file outlines the API specifications for a Fitness Tracker application built with Ktor and MongoDB. The API allows users to manage fitness records including creating new records, updating and deleting records by ID. The API uses the Fitness and FitnessDetails data classes to structure the fitness-related information. paths: /fitness: post: summary: Create a new fitness record requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FitnessRequest' responses: '201': description: Fitness created successfully '400': description: Bad request /fitness/{id}: get: summary: Retrieve fitness record by ID parameters: - name: id in: path required: true schema: type: string responses: '200': description: Successful response content: application/json: example: {} '404': description: Fitness not found delete: summary: Delete fitness record by ID parameters: - name: id in: path required: true schema: type: string responses: '200': description: Fitness deleted successfully '400': description: Bad request '404': description: Fitness not found patch: summary: Update fitness record by ID parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FitnessRequest' responses: '200': description: Fitness updated successfully '400': description: Bad request '404': description: Fitness not found components: schemas: Fitness: type: object properties: id: type: string format: uuid exerciseType: type: string notes: type: string details: $ref: '#/components/schemas/FitnessDetails' required: - id - notes - details FitnessDetails: type: object properties: durationMinutes: type: integer format: int32 distance: type: number format: double caloriesBurned: type: integer format: int32 required: - durationMinutes - distance - caloriesBurned FitnessRequest: type: object properties: exerciseType: type: string notes: type: string details: $ref: '#/components/schemas/FitnessDetails' required: - exerciseType - notes - details

Este archivo define quƩ mƩtodos proporciona nuestra API a travƩs del endpoint /swagger-ui.

5

Este paso implementa los siguientes puntos finales de la API:

  • GET /fitness/{id}: Recupera una entrada de fitness por su ID

  • POST /fitness: Crea una nueva entrada de fitness

  • PATCH /fitness/{id}: Actualiza la entrada de fitness especificada

  • DELETE /fitness/{id}: Elimina la entrada de aptitud fĆ­sica especificada

Cree un paquete routes bajo el paquete application y cree un archivo llamado FitnessRoutes.kt en el paquete routes. Copia el siguiente código en el archivo FitnessRoutes.kt:

package com.mongodb.application.routes import com.mongodb.application.request.FitnessRequestimport com.mongodb.application.request.toDomainimport com.mongodb.domain.ports.FitnessRepositoryimport io.ktor.http.HttpStatusCodeimport io.ktor.server.application.callimport io.ktor.server.request.receiveimport io.ktor.server.response.respondimport io.ktor.server.response.respondTextimport io.ktor.server.routing.routeimport io.ktor.server.routing.Routeimport io.ktor.server.routing.postimport io.ktor.server.routing.deleteimport io.ktor.server.routing.getimport io.ktor.server.routing.patchimport org.bson.types.ObjectIdimport org.koin.ktor.ext.inject fun Route.fitnessRoutes() { val repository by inject<FitnessRepository>() route("/fitness") { post { val fitness = call.receive<FitnessRequest>() val insertedId = repository.insertOne(fitness.toDomain()) call.respond(HttpStatusCode.Created, "Created fitness with id $insertedId") } delete("/{id?}") { val id = call.parameters["id"] ?: return@delete call.respondText( text = "Missing fitness id", status = HttpStatusCode.BadRequest ) val delete: Long = repository.deleteById(ObjectId(id)) if (delete == 1L) { return@delete call.respondText("Fitness Deleted successfully", status = HttpStatusCode.OK) } return@delete call.respondText("Fitness not found", status = HttpStatusCode.NotFound) } get("/{id?}") { val id = call.parameters["id"] if (id.isNullOrEmpty()) { return@get call.respondText( text = "Missing id", status = HttpStatusCode.BadRequest ) } repository.findById(ObjectId(id))?.let { call.respond(it.toResponse()) } ?: call.respondText("No records found for id $id") } patch("/{id?}") { val id = call.parameters["id"] ?: return@patch call.respondText( text = "Missing fitness id", status = HttpStatusCode.BadRequest ) val updated = repository.updateOne(ObjectId(id), call.receive()) call.respondText( text = if (updated == 1L) "Fitness updated successfully" else "Fitness not found", status = if (updated == 1L) HttpStatusCode.OK else HttpStatusCode.NotFound ) } }}

El código anterior define los endpoints de la API y sus controladores.

Antes de ejecutar la aplicación, elimina la carpeta plugins que contiene los archivos HTTP.kt, Routing.kt y Serialization.kt, ya que ya los hemos incluido en el archivo Application.kt.

6

Recupera tu URI de conexión desde tu clúster de MongoDB Atlas. Para obtener mÔs información sobre cómo hacerlo, consulte la sección URI de conexión de la guía Conectar a MongoDB.

Abre el archivo application.conf y añade los siguientes valores de configuración:

-DMONGO_URI= <your connection URI>-DMONGO_DATABASE= <your database name>

Navegue hasta el archivo Application.kt en IntelliJ y haga clic en el botón Run. Ahora puedes acceder a la API navegando a http://localhost:8080/swagger-ui/ en un navegador web.

Para obtener mÔs información sobre Ktor, consulte la documentación de Ktor.

Para ver el código fuente de este tutorial, consulta el repositorio Kotlin Ktor MongoDB Vector Search en GitHub.