You should use enumerations to define a new type that only allows those two values.
An API endpoint represents a resource on a server and has a fixed set of values that it accepts.
For example, the GET request to /api/users is valid, but the POST request to that same endpoint is not.
We can use Swift enums to build this set of valid endpoints and use it’s Associated Values feature to build type-safe and complex requests.
The APILet us start by defining the sample API we’ll be using.
This server has users and posts and responds to the following five endpoints:The API SpecificationThe Users EnumThe users part of the API has two valid endpoints.
The first retrieves a list of all the users in our system and gives us the option to sort the results in newest or alphabetical and have them ordered in descending or ascending order.
We can also specify the maximum number of users we want to receive with the limit option and paginate them with the last_id option.
We can also get a single user with its ID.
We define our base Enum as follows:Users API Endpoint as an enumIt’s really simple.
You can see the get case has an associated ID int value for that user and the all case has three associated values representing the Sorting and Pagination methods.
The last_id value is optional because on the first request we do not have a last_id.
Let’s define UserSort and it’s associated values.
The UserSort and Order enums.
UserSort has its own associated Order value which can be desc or asc and uses raw string values to represent them.
The Posts EnumNow let’s do the same with the Posts enum and create it’s associated PostSort value as well.
Posts API Endpoint as an enumBuilding URLsNow is when the fun begins!.We’ve built the scaffolding that will define our request, and with the power of Swift enums, we can add methods and properties to each that we will use to build the URLs.
I’ve included all the above code in the following sample.
The code for our enums that shows how to construct a URL.
Constructing the RequestNow that our enums are creating the URL, let’s have them also build and return the URLRequest.
To simplify the process, I’ve removed the extra code I’ve already shown above and only implemented the request method for the Post and User enums.
If you’re using another tool that doesn’t use URLRequest you can modify the process to return the object you need.
Creating the URLRequestMaking RequestsNow, I know some of you may be thinking, “Ok this is a lot more code than just using Strings” and you’re completely right, but these enums make it easier and safer for us to build the final request.
These values represent a single resource on our server and we can easily pass them around between functions and classes.
To prove my point, let’s show an example of how we would request all posts from the server using the old String interpolation method and the new enumeration method.
Creating a request with StringsNow let’s see how we can accomplish the same using Enums.
Creating a request with EnumsImagine we use the first set of code throughout our project and suddenly, the Sorting methods on the server change from desc to DESCENDING.
We would have to search through the code to find all instances of the “desc” string and replace it with “DESCENDING”.
But what if you forget one or accidentally misspell one as “DESENDING”?.This is the kind of type-safety enumerations are made to handle!Final ThoughtsI first considered using enums to model our REST endpoints after reading Advanced and Practical Enum usage in Swift.
It took us a while to settle on a method we liked but the results above are basically the what we’re using.
The next steps would be to extract out into different protocols and extensions some of the common methods like the request and endpoint getters.
I’ll that exercise for the reader!Thanks for reading!.I hope you found this post interesting or helpful and if you have any questions let me know in the comments below.
If you want to reach out to me directly check out my website https://sonny.
io.
.