github.com/stripe/stripe-go/v76@v76.25.0/v32_migration_guide.md (about)

     1  # V32 Migration Guide
     2  
     3  Version 32 of stripe-go contains some very sizable breaking changes.
     4  
     5  The major reason that we moved forward on them is that it was previously
     6  impossible when encoding a parameter struct for an API call to make a
     7  distinction between a field that a user had left unset versus a field that had
     8  been set explicitly, but to an empty value. So if we had a parameter struct
     9  like this:
    10  
    11  ``` go
    12  type UsageRecordParams struct {
    13  	Quantity uint64 `form:"quantity"`
    14  }
    15  ```
    16  
    17  We were unable to differentiate these two cases:
    18  
    19  ``` go
    20  // Initialized with no quantity
    21  UsageRecord {}
    22  
    23  // Initialized with an explicitly zero
    24  UsageRecord {
    25      Quantity: 0,
    26  }
    27  ```
    28  
    29  This is because any uninitialized fields on a struct in Go are set to their
    30  type's "zero value", which for an integer is `0`.
    31  
    32  Working around the problem required a secondary field to help explicitly state
    33  that the zero value was intended, which was quite unintuitive for users:
    34  
    35  ``` go
    36  type UsageRecordParams struct {
    37  	Quantity     uint64 `form:"quantity"`
    38  	QuantityZero bool   `form:"quantity,zero"`
    39  }
    40  
    41  UsageRecord {
    42      QuantityZero: true,
    43  }
    44  ```
    45  
    46  To address the problem, we moved every parameter struct over to use pointers
    47  instead. So the above becomes:
    48  
    49  ``` go
    50  type UsageRecordParams struct {
    51  	Quantity *int64 `form:"quantity"`
    52  }
    53  ```
    54  
    55  Because in Go you can't take the address of an inline value (`&0`), we provide
    56  a set of helper functions like `stripe.Int64` specifically for initializing
    57  these structs:
    58  
    59  ``` go
    60  UsageRecord {
    61      Quantity: stripe.Int64(0),
    62  }
    63  ```
    64  
    65  The zero value for pointers is `nil`, so we can now easily determine which
    66  values on a struct were never set, and which ones were explicitly set to a zero
    67  value, thus eliminating the need for the secondary fields like `QuantityZero`.
    68  
    69  Because this is a large change, we also took the opportunity to do some
    70  housekeeping throughout the library. Most of this involves renaming fields and
    71  some resources to be more accurate according to how they're named in Stripe's
    72  REST API, but it also involves some smaller changes like moving some types and
    73  constants around.
    74  
    75  Please see the list below for the complete set of changes.
    76  
    77  ## Major changes
    78  
    79  * All fields on parameter structs (those that end with `*Params`) are now
    80    pointers. Please use the new helper functions to set them:
    81      * `stripe.Bool`
    82      * `stripe.Float64`
    83      * `stripe.Int64`
    84      * `stripe.String`
    85  
    86      This also means that extra fields that used to be solely used for tracking
    87      meaningful zero values like `CouponEmpty` and `QuantityZero` have been
    88      dropped. Use their corresponding field (e.g., `Coupon`, `Quantity`) with an
    89      explicit empty value instead (`stripe.String("")`, `stripe.Int64(0)`).
    90  * Many fields have been renamed so that they're more consistent with their name
    91    in Stripe's REST API. Most of the time, this changes abbreviations to a more
    92    fully expanded form. For example:
    93      * `Desc` becomes `Description`.
    94      * `Live` becomes `Livemode`.
    95  * A few names of API resources (and their corresponding parameter and list
    96    classes) have changed:
    97      * `Fee` becomes `ApplicationFee`.
    98      * `FeeRefund` becomes `ApplicationFeeRefund`.
    99      * `Owner` becomes `AdditionalOwner`.
   100      * `Sub` becomes `Subscription`.
   101      * `SubItem` becomes `SubscriptionItem`.
   102      * `Transaction` becomes `BalanceTransaction`.
   103      * `TxFee` becomes `BalanceTransactionFee`.
   104  * Some sets of constants have been renamed and migrated to the top-level
   105    `stripe` package. All constants now have a prefix according to what they
   106    describe (for example, card brands all start with `CardBrand*` like
   107    `CardBrandVisa`) and all now reside in the `stripe` package (for example
   108    `dispute.Duplicate` is now `stripe.DisputeReasonDuplicate`).
   109  * Some structs that used to be shared between requests and responses are now
   110    broken apart. All API calls should be using only structs that end with a
   111    `*Params` suffix. So for example, if you were using `Address` or `DOB`
   112    before, you should now use `AddressParams` and `DOBParams`.
   113  
   114  ## Other changes
   115  
   116  * All integer values now use `int64` as their type. This means that the
   117    `stripe.Int64` helper function is appropriate for setting all integer values.
   118    This usually doesn't require a change because just setting these fields to a
   119    numerical literal didn't require that the type be explicitly stated.
   120  * `Event.GetObjValue` becomes `Event.GetObjectValue`
   121  * `Params.AddMeta` becomes `Params.AddMetadata`
   122  * `Params.End` and `ListParams.End` become `EndingBefore`, and become a pointer
   123    (use `stripe.String` to set them as with other parameters).
   124  * `Params.Expand` and `ListParams.Expand` (the fields) becomes a slice of
   125    pointers (instead of a slice of strings).
   126  * `Params.Expand` and `ListParams.Expand` (the functions) become `AddExpand`.
   127  * `Params.IdempotencyKey` becomes a pointer.
   128  * `Params.Limit` becomes a pointer.
   129  * `Params.Meta` becomes `Params.Metadata`
   130  * `Params.Start` and `ListParams.Start` become `StartingAfter`
   131  * `Params.StripeAccount` and `ListParams.StripeAccount` become pointers.
   132  * List object data is now accessed with `object.Data` instead of `object.List`.
   133    Nothing changes if you were using iterators and `Next`.
   134  * The previously deprecated `FileUploadParams.File` has been removed. Please
   135    use `FileUploadParams.FileReader` instead.
   136  * The previously deprecated `Params.Account` has been removed. Please use
   137    `Params.StripeAccount` instead.
   138  
   139  As usual, if you find bugs, please [open them on the repository][issues], or
   140  reach out to `support@stripe.com` if you have any other questions.
   141  
   142  [issues]: https://github.com/stripe/stripe-go/issues/new
   143  
   144  <!--
   145  # vim: set tw=79:
   146  -->