Designing Swift APIs

It’s very common to think of APIs as something that is only relevant for packaged code, like SDKs or Frameworks, Back-End services even. But, most definitely, we are all API designers whether we like it or not - even if your code is bundled.
However, designing great APIs while balancing between ease-of-use, capabilities and the fact that different developers have varying levels of knowledge, can be very tricky.

Let’s look at some best practices and techniques that are good to keep in mind when designing various APIs in Swift, and also, how we can create APIs that are both easy to use, non-redundant, and powerful all together.

Transcript

1. Designing Swift APIs Erez Hod Special thanks to !1
2. !2
3. • Active since 2011 • 1,400+ members • 24 meetups to date Where we at? !3
4. • Even greater content • Reach more iOS developers from beginners to advanced • More meetups Where are we headed? !4
5. How can I help? WE WANT YOU To talk about iOS/Swift in our upcoming meetups !5
6. • Name: Erez Hod • Age: 31 • Weight: Noticeable • Personal Motto:
 “If it doesn’t support Dark Mode, then don’t use it…” • Occupations: • Casual Gamer • Sports Cars Lover • Co-Founder of Hero Apps, Ltd !6 About Me
7. !7
8. !8
9. So… What are we going to talk about today? !9
10. Noticeable Code Pain Points • Unclear context • Doesn’t feel intuitive and natural to use • Prone to other developers mistakes 10
11. My Mission Help you design better APIs !11
12. How does that help you? • Saves time & headache: • For developers on your team • For your successors • Improves your team’s scaling level • Improve yourself professionally 12
13. Real World API Example !13
14. Real World API Example struct ChatManager { func doWork(message: TextMessage) -> UIView } !14
15. Real World API Example struct ChatManager { func sendMessageToUser(message: Message, user: User, otherUser: User, messageOptions: MessageOptions) { // ... } } !15
16. How can we make
 this API better? !16
17. First Things First… • What does “API” mean? • Context & Call Sites • Nested Types • Functions Overloading • Strong Typing • Default & Optional function parameters !17
18. First Things First… • What does “API” mean? • Context & Call Sites • Nested Types • Functions Overloading • Strong Typing • Default & Optional function parameters !18
19. What does “API” mean? !19
20. What does “API” mean? What if I told you, every time you write a non-private property or function, you are actually writing an API? !20
21. Great API - Key Characteristics • Balancing ease-of-use & capabilities • The right amount of context • Feels intuitive & natural to use !21
22. Agenda • What does “API” mean? • Context & Call Sites • Nested Types • Functions Overloading • Strong Typing • Default & Optional function parameters !22
23. Context & Call Sites !23
24. struct VideoLibrary { mutating func add(video: Video) { // ... } } Context & Call Sites !24
25. struct VideoLibrary { mutating func add(video: Video) { // ... } } Context & Call Sites !25 library.add(video: video)
26. Context & Call Sites mutating func add(video: Video) !26
27. Context & Call Sites mutating func add(video: Video) mutating func add(_ video: Video) !27
28. Context & Call Sites mutating func add(_ video: Video) !28 library.add(video)
29. extension VideoLibrary { func calculateDiskSpace(_ service: CloudService) -> DiskSpace { // ... } } Context & Call Sites let diskSpace = chatManager.calculateDiskSpace(user.cloudService) !29
30. func calculateDiskSpace(_ service: CloudService) -> DiskSpace { // ... } Context & Call Sites !30 func calculateDiskSpace(leftIn service: CloudService) -> DiskSpace { // ... }
31. Context & Call Sites !31 extension VideoLibrary { func calculateDiskSpace(leftIn service: CloudService) -> DiskSpace } chatManager.calculateDiskSpace(leftIn: user.cloudService)
32. Context & Call Sites
 Summary • Context is important • Add/omit function labels wisely • The call site is what really matters !32
33. Agenda • What does “API” mean? • Context & Call Sites • Nested Types • Functions Overloading • Strong Typing • Default & Optional function parameters !33
34. Nested Types !34
35. Nested Types !35 struct Album { let name: String let videos: [Video] } struct Video { let name: String let author: Author }
36. Nested Types !36 struct Album { let name: String let videos: [Video] }
37. Nested Types !37 extension Video { struct Album { let name: String let videos: [Video] } }
38. Nested Types !38 extension Video { struct Album { let name: String let videos: [Video] } } let album = Video.Album()
39. Agenda • What does “API” mean? • Context & Call Sites • Nested Types • Functions Overloading • Strong Typing • Default & Optional function parameters !39
40. Functions Overloading !40
41. Functions Overloading !41 struct VideoLibrary { mutating func add(_ video: Video) { // ... } mutating func add(_ album: Video.Album) { album.videos.forEach { add($0) } } }
42. Functions Overloading !42 struct VideoLibrary { mutating func add(_ video: Video) { // ... } mutating func add(_ album: Video.Album) { album.videos.forEach { add($0) } } }
43. Functions Overloading !43 struct VideoLibrary { mutating func add(_ video: Video) { // ... } mutating func add(_ album: Video.Album) { album.videos.forEach { add($0) } } }
44. Functions Overloading !44 struct VideoLibrary { mutating func add(_ video: Video) { // ... } mutating func add(_ album: Video.Album) { album.videos.forEach { add($0) } } } library.add(video) library.add(album)
45. Agenda • What does “API” mean? • Context & Call Sites • Nested Types • Functions Overloading • Strong Typing • Default & Optional function parameters !45
46. Strong Typing !46
47. Strong Typing extension VideoLibrary { mutating func update(author: String, for video: Video) { // ... } } library.update(author: user.name, for: video) !47
48. Strong Typing extension VideoLibrary { mutating func update(author: String, for video: Video) { // ... } } library.update(author: user.name, for: video) !48 struct Author { let name: String }
49. Strong Typing extension VideoLibrary { mutating func update(author: Author, for video: Video) { // ... } } library.update(author: user.name, for: video) !49 struct Author { let name: String }
50. Strong Typing extension VideoLibrary { mutating func update(_ author: Author, for video: Video) { // ... } } library.update(author: user.name, for: video) !50 struct Author { let name: String }
51. Strong Typing extension VideoLibrary { mutating func update(_ author: Author, for video: Video) { // ... } } library.update(Author(name: "Steven Spielberg"), for: video) !51 struct Author { let name: String }
52. Questions so far? !52
53. Agenda • What does “API” mean? • Context & Call Sites • Nested Types • Functions Overloading • Strong Typing • Default & Optional function parameters !53
54. Default & Optional Parameters !54
55. struct Networking { func request(url: URL, method: HTTPMethod, headers: Dictionary<String, String>, parameters: Array<URLQueryItem>, body: Dictionary<String, Any>) { // ... } } !55 Default & Optional Parameters
56. struct HTTPHeader { let key: String let value: String } let url = URL(string: "https://my-back-end.com/api/v1/login")! let headers = [ HTTPHeader(key: "Content-Type", value: "application/json"), HTTPHeader(key: "Accept-Language", value: user.language) ] let body = [ HTTPBodyItem(key: "email", value: "erez@hero-apps.io"), HTTPBodyItem(key: "password", value: "awesomePassword") ] !56 struct HTTPBodyItem { let key: String let value: Any } Default & Optional Parameters
57. Default & Optional Parameters struct Networking { func request(url: URL, method: HTTPMethod, headers: Dictionary<String, String>, parameters: Array<URLQueryItem>, body: Dictionary<String, Any>) { // ... } } !57
58. Default & Optional Parameters struct Networking { func request(url: URL, method: HTTPMethod, headers: Dictionary<String, String>, parameters: Array<URLQueryItem>, body: Dictionary<String, Any>) { // ... } } !58 struct Networking { func request(_ url: URL, method: HTTPMethod = .get, headers: Array<HTTPHeader>? = nil, parameters: Array<URLQueryItem>? = nil, body: Array<HTTPBodyItem>? = nil) { // ... } }
59. Default & Optional Parameters !59 struct Networking { func request(_ url: URL, method: HTTPMethod = .get, headers: Array<HTTPHeader>? = nil, parameters: Array<URLQueryItem>? = nil, body: Array<HTTPBodyItem>? = nil) { // ... } }
60. Default & Optional Parameters !60 struct Networking { func request(_ url: URL, method: HTTPMethod = .get, headers: Array<HTTPHeader>? = nil, parameters: Array<URLQueryItem>? = nil, body: Array<HTTPBodyItem>? = nil) { // ... } }
61. Default & Optional Parameters struct Networking { func request(_ url: URL, method: HTTPMethod = .get, headers: Array<HTTPHeader>? = nil, parameters: Array<URLQueryItem>? = nil, body: Array<HTTPBodyItem>? = nil) { // ... } } networking.request(url) // Default GET request networking.request(url, headers: headers) // GET request with headers networking.request(url, method: .post, headers: headers, body: body) // POST request with headers & body !61
62. Agenda • What does “API” mean? • Context & Call Sites • Nested Types • Functions Overloading • Strong Typing • Default & Optional function parameters !62
63. Making our live API example better !63
64. Remember This? struct ChatManager { func sendMessageToUser(message: Message, user: User, otherUser: User, messageOptions: MessageOptions) { // ... } } chatManager.sendMessageToUser(message: message, user: user1, otherUser: user2, messageOptions: options) !64
65. Remember This? struct ChatManager { func sendMessageToUser(message: Message, user: User, otherUser: User, messageOptions: MessageOptions) { // ... } } !65 struct ChatManager { func send(_ message: Message, from currentUser: User, to destinationUser: User, with options: Message.Options? = nil) { // ... } }
66. Remember This? !66 struct ChatManager { func send(_ message: Message, from currentUser: User, to destinationUser: User, with options: Message.Options? = nil) { // ... } }
67. Remember This? !67 struct ChatManager { func send(_ message: Message, from currentUser: User, to destinationUser: User, with options: Message.Options? = nil) { // ... } }
68. Remember This? !68 struct ChatManager { func send(_ message: Message, from currentUser: User, to destinationUser: User, with options: Message.Options? = nil) { // ... } }
69. Remember This? !69 struct ChatManager { func send(_ message: Message, from currentUser: User, to destinationUser: User, with options: Message.Options? = nil) { // ... } }
70. Making it better… chatManager.sendMessageToUser(message: message, user: user1, otherUser: user2, messageOptions: options) !70 chatManager.send(message, from: currentUser, to: destinationUser, with: options) // We can also omit the ‘with options' parameter if we don't need it chatManager.send(message, from: currentUser, to: destinationUser)
71. So, what have we learned? • API design is… • All over your code • Not an absolute science • Some great Swift tips & tricks • Making our APIs clearer and easier to use !71
72. One more thing… !72
73. The $1M Question… “Have I done everything I possibly can to make this API as clear and easy-to-use as possible?” !73
74. “But I don’t want to go among API designers…” !74
75. We’re All API Designers here Oh, you can’t help that… Thank you! !75