HTTP is all about sending and receiving information over the community. Initially it was solely utilized to switch HTML paperwork, however these days we use HTTP to switch CSS, JavaScript, JSON and lots of different information sorts. Based on the requirements, the Content material-Sort and Content material-Size headers can be utilized to have a greater understanding concerning the information contained in the physique of the HTTP request.
Trendy internet servers can robotically ship again these headers primarily based on the thing you come in a request handler operate. That is the case with Hummingbird, it has built-in encoding and decoding help, which makes the information transformation course of actually easy.
For instance if we setup the next route handler and name the hiya endpoint utilizing cURL with the -i flag, the output will comprise a bit extra details about the response. ℹ️
router.get("hiya") { _ in "hiya" }
There are some fundamental headers within the response, the content-type header accommodates the kind of the physique, which is presently a plain textual content with an UTF-8 encoded string, since we have returned a String kind utilizing our Swift code. The content-length is 5, as a result of the character depend of hiya is 5.
There are another headers, however ignore these, the fascinating half for us is the content-type header, and the way it’s injected into the response. Each Hummingbird utility has an encoder and a decoder property. The default values for these are NullEncoder and NullDecoder. The encoders can magically add the correct content material kind header to the response and encode some object right into a HTTP response information. Not all the things is response encodable and decodable by default, however you’ll be able to encode String objects in Hummingbird by default. 👍
Encoding and decoding JSON objects
Most of the server-side Swift methods are used to create JSON-based RESTful API backends for cellular frontends. Hummingbird may also help you with this, because it has built-in encoding and decoding help for JSON objects via the Codable protocol.
First you must import the HummingbirdFoundation library, since it’s a standalone helper instrument constructed across the Basis framework, and that package deal accommodates the Codable kind extensions. Subsequent you must setup the encoder and decoder utilizing a JSONEncoder and JSONDecoder occasion. After this, you’ll be able to simply remodel incoming HTTP physique objects into Swift information constructions and return with them as nicely. Let me present you a fast instance. ⤵️
import Hummingbird
import HummingbirdFoundation
struct Foo: Codable {
let bar: String
let baz: Int
}
extension Foo: HBResponseCodable {}
extension HBApplication {
func configure(_ args: AppArguments) throws {
decoder = JSONDecoder()
encoder = JSONEncoder()
router.submit("foo") { req async throws -> Foo in
guard let foo = strive? req.decode(as: Foo.self) else {
throw HBHTTPError(.badRequest, message: "Invalid request physique.")
}
return foo
}
}
}As you’ll be able to see the kind of the returned content material is now correctly set to utility/json and the size can be offered by default. We have been additionally capable of decode the Foo object from the request physique and robotically encode the thing after we returned with it.
Codable routing works like magic and these days it is a fairly normal strategy if it involves server-side Swift frameworks. Enjoyable reality: this strategy was initially ‘invented’ for Swift by the builders of the Kitura framework. Thanks. 🙏
The HBResponseCodable and the HBResponseEncodable protocols are the essential constructing blocks and the HBRequestDecoder and the HBResponseEncoder are accountable for this magic. They make it attainable to decode a Decodable object from a HBRequest and encode issues right into a HBResponse object and likewise present further headers. If you want to know extra, I extremely advocate to check out the JSONCoding.swift file contained in the framework. 😉
Encoding and decoding HTML kinds
I do not need to get an excessive amount of into the small print of constructing kinds utilizing HTML code, by the way in which there’s a higher approach utilizing SwiftHtml, however I would wish to focus extra on the underlying information switch mechanism and the enctype attribute. There are 3 attainable, however solely two helpful values of the encoding kind:
- utility/x-www-form-urlencoded
- multipart/form-data
URL encoding and decoding is supported out of the field when utilizing HummingbirdFoundation, this can be a easy wrapper across the URL encoding mechanism to simply help information transformation.
decoder = URLEncodedFormDecoder()
encoder = URLEncodedFormEncoder()
In order that’s one technique to course of a URL encoded type, the opposite model relies on the multipart strategy, which has no built-in help in Hummingbird, however you need to use the multipart-kit library from the Vapor framework to course of such kinds. You could find a working instance right here. I even have an article about easy methods to add information utilizing multipart type information requests. So there are many sources on the market, that is why I will not embrace an instance on this article. 😅
Header primarily based encoding and decoding
First we have now to implement a customized request decoder and a response encoder. Within the decoder, we’ll test the Content material-Sort header for a given request and decode the HTTP physique primarily based on that. The encoder will do the very same factor, however the response physique output goes to rely on the Settle for header subject. This is how one can implement it:
struct AppDecoder: HBRequestDecoder {
func decode<T>(
_ kind: T.Sort,
from req: HBRequest
) throws -> T the place T: Decodable {
change req.headers["content-type"].first {
case "utility/json", "utility/json; charset=utf-8":
return strive JSONDecoder().decode(kind, from: req)
case "utility/x-www-form-urlencoded":
return strive URLEncodedFormDecoder().decode(kind, from: req)
default:
throw HBHTTPError(.badRequest)
}
}
}
struct AppEncoder: HBResponseEncoder {
func encode<T>(
_ worth: T,
from req: HBRequest
) throws -> HBResponse the place T: Encodable {
change req.headers["accept"].first {
case "utility/json":
return strive JSONEncoder().encode(worth, from: req)
case "utility/x-www-form-urlencoded":
return strive URLEncodedFormEncoder().encode(worth, from: req)
default:
throw HBHTTPError(.badRequest)
}
}
}Now in case you change the configuration and use the AppEncoder & AppDecoder you need to be capable to reply primarily based on the Settle for header and course of the enter primarily based on the Content material-Sort header.
import Hummingbird
import HummingbirdFoundation
struct Foo: Codable {
let bar: String
let baz: Int
}
extension Foo: HBResponseEncodable {}
extension Foo: HBResponseCodable {}
extension HBApplication {
func configure(_ args: AppArguments) throws {
decoder = AppDecoder()
encoder = AppEncoder()
router.submit("foo") { req async throws -> Foo in
guard let foo = strive? req.decode(as: Foo.self) else {
throw HBHTTPError(.badRequest, message: "Invalid request physique.")
}
return foo
}
}
}Be happy to mess around with some cURL snippets… 👾
# ought to return JSON encoded information
curl -i -X POST http://localhost:8080/foo
-H "Content material-Sort: utility/x-www-form-urlencoded"
-H "Settle for: utility/json"
--data-raw 'bar=bar&baz=42'
# ought to return URL encoded information
curl -i -X POST http://localhost:8080/foo
-H "Content material-Sort: utility/json"
-H "Settle for: utility/x-www-form-urlencoded"
--data-raw '{"bar": "bar", "baz": 42}'
# ought to return with a 400 standing code
curl -i -X POST http://localhost:8080/foo
-H "Content material-Sort: utility/json"
-H "Settle for: multipart/form-data"
--data-raw '{"bar": "bar", "baz": 42}'
So, primarily based on this text you need to be capable to implement help to much more content material sorts by merely extending the app encoder and decoder. After all you might need to import some further package deal dependencies, however that is fantastic.
Uncooked requests and responses
Yet one more little factor, earlier than I finish this text: you’ll be able to entry the uncooked request physique information and ship again a uncooked response utilizing the HBResponse object like this:
router.submit("foo") { req async throws -> HBResponse in
if let buffer = req.physique.buffer {
let rawInputData = buffer.getData(
at: 0,
size: buffer.readableBytes
)
print(rawInputData)
}
if let sequence = req.physique.stream?.sequence {
for strive await chunk in sequence {
print(chunk)
}
}
guard let information = "hiya".information(utilizing: .utf8) else {
throw HBHTTPError(.internalServerError)
}
return .init(
standing: .okay,
headers: .init(),
physique: .byteBuffer(.init(information: information))
)
}For smaller requests, you need to use the req.physique.buffer property and switch it right into a Information kind if wanted. Hummingbird has nice help for the brand new Swift Concurreny API, so you need to use the sequence on the physique stream in case you want chunked reads. Now just one query left:
What sorts ought to I help?
The reply is straightforward: it relies upon. Like actually. These days I began to ditch multipart encoding and I want to speak with my API utilizing REST (JSON) and add information as uncooked HTTP physique. I by no means actually needed to help URL encoding, as a result of in case you submit HTML kinds, you will finally face the necessity of file add and that will not work with URL encoded kinds, however solely with multipart.
In conclusion I would say that the excellent news is that we have now loads of alternatives and if you wish to present help for many of those sorts you do not have to reinvent the wheel in any respect. The multipart-kit library is constructed into Vapor 4, however that is one of many causes I began to love Hummingbird a bit extra, as a result of I can solely embrace what I actually need. Anyway, competitors is an effective factor to have on this case, as a result of hopefully each frameworks will evolve for good… 🙃
