Update union example in README.md (#77)

* Update union example in README.md * Add section for 3.0.7 -> 3.0.8 breaking change
trycourier · May 3, 2024 · 1978cfc · 1978cfc
1 parent 117cf36
commit 1978cfc
Showing 1 changed file with 94 additions and 18 deletions.
diff --git a/README.md b/README.md
@@ -72,33 +72,109 @@ fmt.Printf("Sent message %s\n", sendResponse.RequestId)
 
 ## Unions
 
-Our API, particularly the send method, uses several unions. Our Go SDK provides
-strongly typed factories to construct these unions, such as `courier.NewMessageFromContentMessage(...)`.
+Our API, particularly the send method, uses several unions. Our Go SDK defines structs
+to construct these unions, such as `courier.Message`, shown below:
 
 ```go
 import (
   courier "github.com/trycourier/courier-go/v3"
 )
 
-courier.SendMessageRequest{
-  // Construct a template message
-  Message: courier.NewMessageFromContentMessage(&courier.ContentMessage{
-    // Construct a single recepient
-    To: courier.NewMessageRecipientFromRecipient(
-      // Construct a single recepient that is a user recepient
-      courier.NewRecipientFromUserRecipient(&courier.UserRecipient{
-        Email: courier.String("marty_mcfly@email.com"),
-        Data: &courier.MessageData{
-          "name": "Marty",
+request := &courier.SendMessageRequest{
+  // Construct a content message.
+  Message: &courier.Message{
+    ContentMessage: &courier.ContentMessage{
+      // Construct a single recepient that is a user recepient.
+      To: &courier.MessageRecipient{
+        Recipient: &courier.Recipient{
+          UserRecipient: &courier.UserRecipient{
+            Email: courier.String("marty_mcfly@email.com"),
+            Data: &courier.MessageData{
+              "name": "Marty",
+            },
+          },
         },
-      })),
-    // Construct content from elemental content sugar
-    Content: courier.NewContentFromElementalContentSugar(&courier.ElementalContentSugar{
+      },
+      // Construct content from elemental content sugar.
+      Content: &courier.Content{
+        ElementalContentSugar: &courier.ElementalContentSugar{
+          Title: "Back to the Future",
+          Body:  "Oh my {{name}}, we need 1.21 Gigawatts!",
+        },
+      },
+    },
+  },
+}
+```
+
+### Breaking change (3.0.7 -> 3.0.8)
+
+We introduced a better union construction experience in [3.0.8](https://github.com/trycourier/courier-go/releases/tag/v3.0.8).
+For example, the `courier.Message` type was previously constructed with the following:
+
+```go
+import (
+  courier "github.com/trycourier/courier-go/v3"
+)
+
+request := courier.SendMessageRequest{
+  // Construct a content message.
+  Message: courier.NewMessageFromContentMessage(
+    &courier.ContentMessage{
+      // Construct a single recepient that is a user recepient.
+      To: courier.NewMessageRecipientFromRecipient(
+        courier.NewRecipientFromUserRecipient(
+          &courier.UserRecipient{
+            Email: courier.String("marty_mcfly@email.com"),
+            Data: &courier.MessageData{
+              "name": "Marty",
+            },
+          },
+        ),
+      ),
+      // Construct content from elemental content sugar.
+      Content: courier.NewContentFromElementalContentSugar(
+        &courier.ElementalContentSugar{
+          Title: "Back to the Future",
+          Body:  "Oh my {{name}}, we need 1.21 Gigawatts!",
+        },
+      ),
+    },
+  ),
+}
+```
+
+Although the construction looks fairly similar, the old approach required navigating a
+variety of cumebersome constructor function names (e.g. `courier.NewContentFromElementalContentSugar`).
+
+The new approach drops these constructors entirely, which simplifies the experience significantly.
+Migrating from the old approach is as simple as setting the concrete type to the appropriate
+field like so:
+
+**Before**
+
+```go
+  ...
+  Content: courier.NewContentFromElementalContentSugar(
+    &courier.ElementalContentSugar{
       Title: "Back to the Future",
       Body:  "Oh my {{name}}, we need 1.21 Gigawatts!",
-    }),
-  }),
-}
+    },
+  ),
+  ...
+```
+
+**After**
+
+```go
+  ...
+  Content: &courier.Content{
+    ElementalContentSugar: &courier.ElementalContentSugar{
+      Title: "Back to the Future",
+      Body:  "Oh my {{name}}, we need 1.21 Gigawatts!",
+    },
+  },
+  ...
 ```
 
 ## Timeouts