Creating an API

This page provides a guide to creating a REST API with Osiris. Many of the features shown here can be seen in the example API in any project generated by Osiris. The example API is defined in the file ApiDefinition.kt and is a useful reference and a good starting point when building an API.

In order to create an API, the minimum you must do is create a top-level property of type Api. This must be called api and be in the core module of your application.

val api = api<...> {
    ...
}

A Api is created by the api function in the package ws.osiris.core. This provides a DSL for defining the endpoints and the code that runs when they are invoked. The DSL is inspired by Sinatra and the many similar frameworks such as Spark Java and Scalatra.

The type parameter of the api function is a subtype of ComponentsProvider. This can be safely ignored for now and is covered in detail in the section on components.

Creating an Endpoint

The simplest possible endpoint looks something like this:

val api = api<ComponentsProvider> {

    get("/helloworld") { req ->
        "hello, world!"
    }
}

This defines a single endpoint at /helloworld that responds to a GET request with the text "hello, world!". The parameter req is a Request instance containing the headers, parameter and body of the HTTP request. This is covered in detail later.

There are functions similar to get for defining endpoints to handle the other HTTP methods: post, put, update, options, patch and delete.

Paths Containing Variables

Routes can be defined containing variable segments that match any path. For example

get("/orders/{orderId}") { req ->
    ...
}

The value of the variable orderId is available from the pathParams property of the request:

get("/orders/{orderId}") { req ->
    val orderId = req.pathParams["orderId"]
    ...
}

A path can contain multiple variable segments, for example /customers/{customerId}/orders/{orderId}.

Grouping Endpoints Using path

If there are multiple endpoints with a common prefix they can be grouped using the path function to avoid repeating the prefix:

path("/customers") {
    // The path is /customers/{customerId}
    get("/{customerId}") -> req
        ...
    }
    // The path is /customers/{customerId}/orders/{orderId}
    get("/{customerId}/orders/{orderId}") -> req
        ...
    }
}