{"id":9738,"date":"2025-03-31T14:00:00","date_gmt":"2025-03-31T11:00:00","guid":{"rendered":"https:\/\/handoli.com\/index.php\/2025\/03\/31\/modern-url-construction-in-swift\/"},"modified":"2025-03-31T14:00:00","modified_gmt":"2025-03-31T11:00:00","slug":"modern-url-construction-in-swift","status":"publish","type":"post","link":"https:\/\/handoli.com\/index.php\/2025\/03\/31\/modern-url-construction-in-swift\/","title":{"rendered":"Modern URL construction in Swift"},"content":{"rendered":"

These days, most applications need to work with URLs in some form. Perhaps they\u2019re used to make network calls, to read and write files, or to perform various kinds of database operations. In Swift, URLs are by convention (and through the design of Apple\u2019s frameworks) represented using the dedicated URL<\/code> type, rather than just using plain strings, which ensures that we\u2019re actually working with valid, properly formatted URLs.<\/p>\n

However, that also means that anytime that we have a string that we wish to treat as a URL, we have to perform a conversion that returns an optional \u2014 such as in this case:<\/p>\n

guard let<\/span> url = URL<\/span>(string: \"https:\/\/swiftbysundell.com\"<\/span>) else<\/span> {\n    \/\/ Hmmm... now what?<\/span>\n    return<\/span> print<\/span>(\"Invalid URL\"<\/span>)\n}<\/code><\/pre>\n
For URLs such as the one above, which are constructed using static string literals, using a conversion that can fail does arguably feel a bit unnecessary<\/em>. After all, there\u2019s no runtime variance involved here, so there\u2019s really no significant risk that the above kind of conversion will result in nil<\/code>, unless we\u2019ve made a typo within our code.<\/p>\n
So, when working with such static URLs, it\u2019s very common to simply use force unwrapping to turn the resulting optional URL<\/code> into a non-optional one:<\/p>\n
let<\/span> url = URL<\/span>(string: \"https:\/\/swiftbysundell.com\"<\/span>)!<\/code><\/pre>\n
However, having to do the above kind of force unwrapping manually every time we want to construct a URL is not quite ideal \u2014 so let\u2019s see if we can improve things. First, let\u2019s extend URL<\/code> with an initializer that accepts a StaticString<\/code> (which are Swift string literals without any kind of interpolation or dynamic components), within which we can perform the required unwrapping, but this time we\u2019ll use a custom fatalError<\/code> message in case the conversion to a URL<\/code> failed:<\/p>\n
extension<\/span> URL<\/span> {\n    init<\/span>(staticString: StaticString<\/span>) {\n        guard let<\/span> url = Self<\/span>(string: \"<\/span>(staticString)\"<\/span>) else<\/span> {\n            fatalError<\/span>(\"Invalid static URL string:<\/span> (staticString)\"<\/span>)\n        }\n\n        self<\/span> = url\n    }\n}<\/code><\/pre>\n
\n
Using a custom fatalError<\/code> call in situations when we have<\/em> to force unwrap a value is in general a good practice, since that lets us provide additional context that can be incredibly useful if we ever need to debug a crash caused by a nil<\/code> value.<\/p>\n<\/blockquote>\n
With the above in place, we can now easily convert any static string within our code base into a URL<\/code>, without having to deal with optionals at every single call site:<\/p>\n
let<\/span> url = URL<\/span>(staticString: \"https:\/\/swiftbysundell.com\"<\/span>)<\/code><\/pre>\n
Nice! Up until Swift 5.9, the above approach was more or less the best simple way to work with inline, static URLs in a non-optional manner (without requiring any external tools, such as code generation). However, Swift 5.9 introduced a new feature that can be incredibly useful in situations like this \u2014 macros<\/em>.<\/p>\n
It\u2019s macro time!<\/h2>\n
Let\u2019s see if we can write a Swift macro that\u2019ll let us not just convert, but also validate<\/em> static URL strings at compile time. We\u2019ll start by jumping over to the command line, where we\u2019ll run the following command to create a new macro-based Swift package:<\/p>\n
swift package init --type macro --name StaticURL<\/code><\/pre>\n
One thing that\u2019s neat about macro packages, is that they come pre-filled with most of the boilerplate that we\u2019ll need to define and vend our macro to any other targets that wish to use it \u2014 and it just so happens that the stringify<\/code> macro that\u2019s added as an example is the exact same type of macro that we\u2019re looking to add \u2014 a freestanding expression macro<\/em>.<\/p>\n
So let\u2019s go ahead and simply rename the definition of stringify<\/code> to staticURL<\/code>, and change its input and output types to match the URL<\/code> extension we created earlier:<\/p>\n
import<\/span> Foundation\n\n@freestanding<\/span>(expression)\npublic macro<\/span> staticURL(_<\/span> value: StaticString<\/span>) -> URL<\/span> = #externalMacro<\/span>(\n    module: \"StaticURLMacros\"<\/span>,\n    type: \"StaticURLMacro\"<\/span>\n)<\/code><\/pre>\n
Next, let\u2019s rename the StringifyMacro<\/code> implementation to StaticURLMacro<\/code> (matching the above definition\u2019s type<\/code> argument), and replace its previous expansion<\/code> code with some logic that first ensures that the passed argument is indeed a string literal (although the Swift type system should already have verified that for us), and then extracts the string and attempts to construct a URL using it.<\/p>\n
If all checks pass, then we generate the same kind of force-unwrapping URL<\/code> construction code that we manually used to write, which will be the output of our macro. Here\u2019s what all of that looks like:<\/p>\n
public struct<\/span> StaticURLMacro: ExpressionMacro<\/span> {\n    public static func<\/span> expansion(\n        of node: some<\/span> FreestandingMacroExpansionSyntax<\/span>,\n        in context: some<\/span> MacroExpansionContext<\/span>\n    ) throws<\/span> -> ExprSyntax<\/span> {\n        \/\/ Verify that a string literal was passed, and extract\n        \/\/ the first segment. We can be sure that only one\n        \/\/ segment exists, since we're only accepting static\n        \/\/ strings (which cannot have any dynamic components):<\/span>\n        guard let<\/span> argument = node.arguments<\/span>.first<\/span>?.expression<\/span>,\n              let<\/span> literal = argument.as<\/span>(StringLiteralExprSyntax<\/span>.self<\/span>),\n              case<\/span> .stringSegment<\/span>(let<\/span> segment) = literal.segments<\/span>.first<\/span>\n        else<\/span> {\n            throw<\/span> StaticURLMacroError<\/span>.notAStringLiteral<\/span>\n        }\n        \n        \/\/ Verify that the passed string is indeed a valid URL:<\/span>\n        guard<\/span> URL<\/span>(string: segment.content<\/span>.text<\/span>) != nil else<\/span> {\n            throw<\/span> StaticURLMacroError<\/span>.invalidURL<\/span>\n        }\n\n        \/\/ Generate the code required to construct a URL value\n        \/\/ for the passed string at runtime:<\/span>\n        return<\/span> \"Foundation.URL(string:<\/span> (argument))!\"<\/span>\n    }\n}<\/code><\/pre>\n
\n
Note how we prefix the URL<\/code> type with its parent module (Foundation<\/code>) above. That\u2019s to avoid conflicts if our macro is used within a context that has declared its own URL<\/code> type. Applying such prefixes isn\u2019t typically necessary when writing code manually, but is a good practice when writing macros, since we don\u2019t know up-front exactly where our macros will end up being used.<\/p>\n<\/blockquote>\n
With our macro implementation done, all that remains is to define the StaticURLMacroError<\/code> type that\u2019s used above, and to update our CompilerPlugin<\/code> to provide the correct macro type:<\/p>\n
enum<\/span> StaticURLMacroError: String<\/span>, Error<\/span>, CustomStringConvertible<\/span> {\n    case<\/span> notAStringLiteral = \"Argument is not a string literal\"<\/span>\n    case<\/span> invalidURL = \"Argument is not a valid URL\"<\/span>\n\n    public var<\/span> description: String<\/span> { rawValue }\n}\n\n@main struct<\/span> StaticURLPlugin: CompilerPlugin<\/span> {\n    let<\/span> providingMacros: [Macro<\/span>.Type<\/span>] = [StaticURLMacro<\/span>.self<\/span>]\n}<\/code><\/pre>\n
With all those pieces in place, if we integrate our new StaticURL<\/code> macro package within an application, then we can now easily define static, 100% compile-time validated URLs wherever we\u2019d like:<\/p>\n
let<\/span> url = #staticURL<\/span>(\"https:\/\/swiftbysundell.com\"<\/span>)<\/code><\/pre>\n
Neat! It could definitely be argued that using a macro isn\u2019t really necessary for a use case like this, given that our earlier StaticString<\/code>-based extension approach worked just fine (apart from the danger of typos). Like in many cases when working with Swift, this is essentially a trade-off between increased complexity and compile-time safety, and whether or not the additional complexity of a macro will be worth it will likely vary from project to project.<\/p>\n
Dynamic components<\/h2>\n
So far, we\u2019ve been working with URLs that are known at compile time, but what about ones that have to be constructed at runtime? For example, here we\u2019re using string interpolation to define a URL that\u2019ll be used to load User<\/code> data from a given web API endpoint:<\/p>\n
actor<\/span> NetworkingService {\n    private static let<\/span> baseURL = \"https:\/\/api.myapp.com\"<\/span>\n    ...\n\n    func<\/span> loadUser(withID id: User<\/span>.ID<\/span>) async throws<\/span> -> User<\/span> {\n        guard let<\/span> url = URL<\/span>(\n            string: \"<\/span>(Self<\/span>.baseURL<\/span>)\/users\/<\/span>(id)?refresh=true\"<\/span>\n        ) else<\/span> {\n            throw<\/span> NetworkingError<\/span>.invalidURL<\/span>\n        }\n\n        ...\n    }\n}<\/code><\/pre>\n
Here we\u2019re facing a very similar problem as when working with static URLs \u2014 when reading the above code, we can see that there\u2019s no way that the performed URL<\/code> conversion will ever result in nil<\/code>, given that our baseURL<\/code> and \/users\/<\/code> strings are both static, and if we assume that User.ID<\/code> values are always URL-safe.<\/p>\n
So would it be possible to convince the compiler that a nil<\/code> result can never occur, even when working with dynamic URL components? An initial idea might be to use Foundation\u2019s dedicated URLComponents<\/code> builder \u2014 which offers a structured way to construct dynamic URLs.<\/p>\n
While that approach does<\/em> have some key advantages over using string interpolation (since we\u2019re now assigning values to explicit parts of the URL we\u2019re building, rather than just working with a loosely formed string) \u2014 it\u2019s significantly more verbose in comparison, while still not getting rid of having to unwrap our URL as an optional:<\/p>\n
actor<\/span> NetworkingService {\n    private static let<\/span> baseURLComponents = {\n        var<\/span> components = URLComponents<\/span>()\n        components.scheme<\/span> = \"https\"<\/span>\n        components.host<\/span> = \"api.myapp.com\"<\/span>\n        return<\/span> components\n    }()\n    \n    ...\n\n    func<\/span> loadUser(withID id: User<\/span>.ID<\/span>) async throws<\/span> -> User<\/span> {\n        var<\/span> urlComponents = Self<\/span>.baseURLComponents<\/span>\n        urlComponents.path<\/span> = \"\/users\/<\/span>(id)\"<\/span>\n        urlComponents.queryItems<\/span> = [\n            URLQueryItem<\/span>(name: \"refresh\"<\/span>, value: \"true\"<\/span>)\n        ]\n\n        guard let<\/span> url = urlComponents.url<\/span> else<\/span> {\n            throw<\/span> NetworkingError<\/span>.invalidURL<\/span>\n        }\n\n        ...\n    }\n}<\/code><\/pre>\n
Thankfully, it turns out that there\u2019s a much simpler suite of APIs for dynamic URL construction that were introduced in iOS 16 (and the other 2022 Apple operating system versions) that \u2014 when combined with our static URL handling code from before \u2014 lets us both completely get rid of optionals, and gives us a really nice syntax for constructing our API call URL.<\/p>\n
If we declare our base URL as a static URL<\/code> value (rather than a string, or a URLComponents<\/code> value), then we can simply call different overloads of the appending<\/code> API on that value to construct our dynamic URL in a completely optional-free manner \u2014 like this:<\/p>\n
actor<\/span> NetworkingService {\n    private static let<\/span> baseURL = #staticURL<\/span>(\"https:\/\/api.myapp.com\"<\/span>)\n    ...\n\n    func<\/span> loadUser(withID id: User<\/span>.ID<\/span>) async throws<\/span> -> User<\/span> {\n        let<\/span> url = Self<\/span>.baseURL<\/span>\n            .appending<\/span>(components: \"users\"<\/span>, id)\n            .appending<\/span>(queryItems: [\n                URLQueryItem<\/span>(name: \"refresh\"<\/span>, value: \"true\"<\/span>)\n            ])\n            \n        ...\n    }\n}<\/code><\/pre>\n
Very nice! And the good news is that we\u2019re not limited to just using the above kind of solution when constructing URLs used to perform network calls \u2014 we can also use the same suite of APIs when working with file system URLs that we\u2019d previously resolve using FileManager<\/code>, such as in this example:<\/p>\n
private extension<\/span> NetworkingService<\/span> {\n    func<\/span> cacheResponseOnDisk(_<\/span> response: Response<\/span>) throws<\/span> {\n        guard let<\/span> cacheFolderURL = FileManager<\/span>.default<\/span>.urls<\/span>(\n            for: .cachesDirectory<\/span>,\n            in: .userDomainMask<\/span>\n        ).first<\/span> else<\/span> {\n            throw<\/span> NetworkingError<\/span>.failedToResolveCacheFolder<\/span>\n        }\n\n        ...\n    }\n}<\/code><\/pre>\n
If we now convert the above code to use the new URL construction APIs, then we\u2019ll end up with a another non-optional solution, just as when constructing our web API URL:<\/p>\n
private extension<\/span> NetworkingService<\/span> {\n    func<\/span> cacheResponseOnDisk(_<\/span> response: Response<\/span>) throws<\/span> {\n        let<\/span> cacheURL = URL<\/span>\n            .cachesDirectory<\/span>\n            .appending<\/span>(component: response.cacheID<\/span>)\n\n        ...\n    }\n}<\/code><\/pre>\n
URL<\/code> now also contains a number of other static properties that can be used to reference common folders on Apple\u2019s platforms, such as the home and temporary directories \u2014 all of which hold a predictable, non-optional value:<\/p>\n
URL<\/span>.homeDirectory<\/span>\nURL<\/span>.documentsDirectory<\/span>\nURL<\/span>.desktopDirectory<\/span>\nURL<\/span>.temporaryDirectory<\/span><\/code><\/pre>\n
So, as long as we\u2019re targeting the equivalent of iOS 16 or above within a given project, then we\u2019re now able to quite easily construct both web and file system URLs, even when they contain dynamic paths and components, such as query items.<\/p>\n
Conclusion<\/h2>\n
Using Foundation\u2019s modern URL construction APIs to be able to avoid optionals when creating URL<\/code> values doesn\u2019t just simplify our code, it also reduces the risk of bugs and crashes, and further lets us work with URLs in more structured ways \u2014 by replacing things like string interpolation with dedicated APIs for appending path components and query items.<\/p>\n
I hope you\u2019ve enjoyed reading this first Swift by Sundell article in over two years, and that you\u2019ll find it useful when working on your Swift projects. If you have any questions, feedback, or comments, then feel free to reach out via either Mastodon<\/a> or Bluesky<\/a>.<\/p>\n
Thanks for reading \u2014 and hey, it\u2019s good to be back!<\/p>","protected":false},"excerpt":{"rendered":"
These days, most applications need to work with URLs in some form. Perhaps they\u2019re used to make network calls, to read and write files, or to perform various kinds of database operations. In Swift, URLs are by convention (and through the design of Apple\u2019s frameworks) represented using the dedicated URL type, rather than just using […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rop_custom_images_group":[],"rop_custom_messages_group":[],"rop_publish_now":"initial","rop_publish_now_accounts":[],"rop_publish_now_history":[],"rop_publish_now_status":"pending","footnotes":""},"categories":[1,15],"tags":[],"class_list":["post-9738","post","type-post","status-publish","format-standard","hentry","category-explore","category-world"],"_links":{"self":[{"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/posts\/9738","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/comments?post=9738"}],"version-history":[{"count":0,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/posts\/9738\/revisions"}],"wp:attachment":[{"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/media?parent=9738"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/categories?post=9738"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/handoli.com\/index.php\/wp-json\/wp\/v2\/tags?post=9738"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}