From 4bb05b1f4181bd7e124774eeefd8d71195a14a2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Mon, 9 Feb 2026 23:03:00 +0100 Subject: [PATCH] docs(api): Improve the documentation --- api/README.md | 10 +++++----- api/src/commonMain/kotlin/ResolvedEndpoint.kt | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/api/README.md b/api/README.md index 7067bdf..1e55774 100644 --- a/api/README.md +++ b/api/README.md @@ -6,22 +6,22 @@ Describe your Ktor API in code shared between the client and the server. -When creating fullstack projects, using both Ktor as a client and a server, we need to make sure we are calling the same endpoints on both sides, with the same expected DTOs, etc. +When creating fullstack projects, using both Ktor as a client and a server, we need to make sure we are calling the same endpoints on both sides, with the same expected DTOs, expect the same failures, etc. -Using Kotlin Multiplatform and KotlinX.Serialization, we can easily share DTOs, but the structure of our API is often more than that. +Using Kotlin Multiplatform and KotlinX.Serialization, we can easily share DTOs—but the structure of the API isn't as easy to share. ## Declaring a schema Spine is a library to declare a schema of our API in pure Kotlin. Once it is declared, we can use it identically on the client and server sides. +First, declare a dependency on `dev.opensavvy.spine:api`. + We define that: - [a **resource**](opensavvy.spine.api.Resource) is an imaginary data collection, - [an **endpoint**](opensavvy.spine.api.AnyEndpoint) is a single operation that acts on a given resource. -In HTTP terms, a resource is a URI, and an endpoint is a record of a URI, an HTTP method, a specific request body type… - -Typically, resources are declared as singletons: +We can declare the structure of our API like this: ```kotlin // Declare our root endpoint: /v1 object Api : RootResource("v1") { diff --git a/api/src/commonMain/kotlin/ResolvedEndpoint.kt b/api/src/commonMain/kotlin/ResolvedEndpoint.kt index 9f2e523..1924758 100644 --- a/api/src/commonMain/kotlin/ResolvedEndpoint.kt +++ b/api/src/commonMain/kotlin/ResolvedEndpoint.kt @@ -4,8 +4,8 @@ package opensavvy.spine.api * A resolved [Endpoint][AnyEndpoint]. * * The [AnyEndpoint] interface represents the _declaration_ of an endpoint. - * For example, `GET /api/users/{user}` is not a 'real' endpoint. - * This class, [ResolvedEndpoint], represents 'real' endpoints: 'GET /api/users/111' and 'GET /api/users/222' are possible + * For example, `GET /api/users/{user}` is not a 'real' endpoint: each user has its own endpoint. + * This class, [ResolvedEndpoint], represents 'real' endpoints: `GET /api/users/111` and `GET /api/users/222` are possible * values of this class. * * To resolve an endpoint, start by [resolving its resource][ResolvedResource] then follow with the endpoint: -- 2.51.2