Since the release of Kitura 2.0 last year, a series of incremental enhancements have been made, via the Kitura Evolution process, in response to user feedback, and a number of contributions from the community.

Kitura 2.1, released in December, added support for Range Requests (#1161), array support for query parameters (#1174), and the option to return a single Codable result from a GET when no id is specified (#1176).

Kitura 2.2 was released in January, and introduces Codable APIs for query parameters (Kitura Evolution Proposals #0002 – Query Parameters Enhancement and #0003 – Codable Query Parameters).

Today, we are happy to announce the release of Kitura 2.3, which includes support for Swift 4.1, and a number of enhancements:

Codable Routing support for URLEncoded forms (#1228)


Codable Routing now allows requests to be sent using the  application/x-www-form-urlencoded  encoding, whereas previously only JSON representation was supported. This enables your Kitura application to receive form data in a convenient and type-safe way. As an example, let’s map a form that sends ¬†id=4&name=David¬† to a Swift type:

    struct User: Codable {
        let id: Int
        let name: String
    }

This would previously require the following boilerplate code:

    router.post("/form", middleware: BodyParser())

    router.post("/form") { request, response, next in
        guard let encodedBody = request.body,
            case .urlEncoded(let body) = encodedBody,
            let idString = body["id"],
            let id = Int(idString),
            let name = body["name"]
        else {
            return try response.status(.unprocessableEntity).end()
        }
        let user = User(id: id, name: name)
        // Application logic
        response.status(.created).send(json: user)
        next()
    }

In Kitura 2.3, this can be simplified to the following:

    router.post("/form") { (user: User, respondWith: (User?, RequestError?) -> Void) in
        // Application logic
        respondWith(user, nil)
    }

Details of how urlencoded fields are mapped to your Swift Codable type are covered in Kitura Evolution Proposal #0003 – Codable Query Parameters.

Support for sending a Codable body with a RequestError response (#1214)


This change allows codable route handlers to customise the body of error responses. Previously, when sending a RequestError it was not possible to send a response body.

An example of where this feature is helpful is in the Health route that is generated by the Kitura CLI, which can be used for monitoring the overall health of a Swift application. When the application is healthy, this responds with  HTTP 200 OK , and in the event of a problem, it responds with  HTTP 503 Service Unavailable . In both cases, it should send a JSON payload further describing the status of the application.

This is now possible in the error case by specifying:

    respondWith(nil, RequestError(.serviceUnavailable, body: health.status))

Support for sending arrays of tuples of (Identifier, Codable) – (#1223)


This allows for an ordered array of Codable elements to be sent along with their respective Identifiers, encoded in JSON as an array of dictionaries.  The tuples are converted to a Dictionary representation, as tuples themselves are not Codable.

An example of where this is required is in the recently announced Swift-Kuery-ORM, to support returning a set of Models with their respective identifiers Рthe primary key for the Model Рrepresented as tuples.  For example, to retrieve all persisted instances of a Model:

    struct Fruit: Model {
        let name: String
        let price: Int
    }

    router.get("/fruits") { (respondWith: ([(Int, Fruit)]?, RequestError?) -> Void) in
        Fruit.findAll(respondWith)
    }

Which results in the following JSON:

[
    {"1": {"name": "Apple", "price": 45}},
    {"2": {"name": "Banana", "price": 25}},
    {"3": {"name": "Pear", "price": 50}}
]

Bridge KituraNet.HTTPStatusCode (#1217)


The HTTPStatusCode type is defined in KituraNet, but exposed via Kitura’s RouterResponse API as a means of setting the status code for a response. It is no longer necessary to import KituraNet in order to refer to the HTTPStatusCode type explicitly, for example when setting a status code:

    response.status(HTTPStatusCode.unauthorized)

New convenience API to simplify development of CodableRouter extensions (#1222)


This introduces a CodableHelpers API, which represents the building blocks of Codable routing. Besides reducing code duplication, it aims to make future extensions to the Codable Router simpler to write.

Documentation


A considerable focus has been on documentation improvement for this release, particularly in the areas of Routing and SSL configuration, which are reflected in the API reference on kitura.io.





Join the discussion on Slack Learn more at kitura.io Star Kitura on GitHub

Join The Discussion

Your email address will not be published. Required fields are marked *