Passing parameters to Restful API with Swift Codable

Codable made it convinient for many things. This is especially useful when creating a restful app. Because it is necessary to decode the serialized object. Codable makes it super easy to convert a JSON object into a domain model. (Of course there are still some inconveniences…)

Converting received data to model objects has become very easy. But when sending data, it is not easy to know where Codable makes it easier.
This is because it is very rare to directly convert domain model objects into parameters of Restful API. If you change existing design to use Codable instead of applying it to existing design, you can take advantage of it. I want call it the Codable Driven Design :-)

Crassical way

To pass parameters to the Restful API, you need to add variables to the Dictionary. This is a very classic form of Objective-C method. This is a sign up handling code almost all restful apps should include.

Add the passed method parameters to the params dictionary. Then passes the params Dictionary to the HTTP Client object for low-level processing that actually calls the API. And it delivers success and failure block to receive result.

Crassical Swift style

Here is the Swift 2 source code for the same function. It was written before Codable was released.

Here is also the code to add the method parameters to the dictionary p. Since it do not use Promise (or Observable / Disposable), it still passing success closure to the callAPI. It then returns a Failure object so that the caller can add failure handling.

The shortcomings of traditional ways

The two examples above have two drawbacks.

First, when a method parameter is added or deleted, all relevant code must be modified. Of course, Swift supports default parameter values, so you can flexibly deal with these situations. But if you need to pass values ​​only to a specific item in that method that has multiple parameters with default values, you must set default value for all other items manually. Therefore, the default parameter value is not a complete solution.

Second, you must manually add method parameters to Dictionary. Both examples have code like p [“name”] = name, p [“birthday”] = b. And it is very annoying in itself.

Codable can help to reduce this kind of boilerplate code. Let’s take a third example.

Modern Swift Style

As in the previous examples, this is a method that calls the API to add a new user. Here we have replaced the parameters with an instance of Structure that follows an Encodable named NewUserParams. We then call the dictionary method to convert it to a Dictionary. And pass it to the multipartCall method.

There is no boilerplate code. It is now possible to call the method once. How can Structure become a Dictionary? How does the dictionary method do this? The answer is Codable.

This is the source code for the DictionaryEncodable protocol. It conforms to the Encodable protocol. And it includes a dictionary method that serializes itself to a JSON object using the JSONEncoder. Thus, a structure that conforms to the DictionaryEncodable can be converted to a Dictionary simply by calling the dictionary method.

We can create a structure containing the parameters of the Restful API, simply change it to a Dictionary and pass it to the next step. We no longer need to add method parameters to the Dictionary. And no longer need to modify the relevant parts when the parameters of Restful API changed.

In addition, Restful API parameter list can be easily grasped in a structured form. You can also easily distinguish members of structs from required and non-required items by using Swift Optional.

In this way, I noticed how not only the data received from the Restful API, but also the data to be transmitted, can be handled easily through Codable.
We also looked at the disadvantages of the existing approach to send parameters and how the new approach to using Swift Codable can overcome it. In short, through structured parameters.

Determining whether or not to structure multiple parameters always occurs in the programming process. I chose the structured parameters. And I think it is a good idea to intentionally structure it in certain parts in order to use Swift Codable. I hope that more developers will be able to implement the desired functionality quickly and easily through the new features of Swift.