Skip to content

Latest commit

 

History

History
125 lines (95 loc) · 5.6 KB

UPGRADING.md

File metadata and controls

125 lines (95 loc) · 5.6 KB
Raw

MessageBird go-rest-api upgrading guide

This guide documents breaking changes across major versions and should be taken into account when updating your dependencies.

v4.2.1 -> v5.0.0

Package structure

The most obvious change in this version is the new package structure. Nearly all code used to live in the messagebird package - v5 changes this.

All resources (balance, voicemessage et al) are now moved to their own packages. This also means the functions no longer take the client as a receiver, but as their first parameter.

Let's see some code. We'll fetch the balance for your account.

Before:

client := messagebird.New("YOUR_ACCESS_KEY")
balance, err := client.Balance()

// ...

After:

client := messagebird.New("YOUR_ACCESS_KEY")
balance, err := balance.Read(client)

// ...

Naming

Functions

Some function names have changed. They are now more consistent across the several resources(/packages).

Typically, the HTTP method for the underlaying API calls determine the function's name. Here's an overview.

HTTP method Function name Note
GET List() Lists a resource, e.g. /some-resource
GET Read() Retrieves a single resource, e.g. /some-resource/{resourceId}
POST Create() -

Resources

Previously, SMS messages were referred to simply as messages (e.g. client.NewMessage()) . The package that takes care of this now is named sms. Naming it message is a bad idea, and smsmessage doesn't look very friendly.

MMS messages are handled by the mms package.

Many structs have been renamed too. We used to have messagebird.MMSMessageParams, but we don't want any stuttering like mms.MMSMessageParams. That's now simply mms.Params.

Recipient

The Recipient.Recipient field used to be of type int. On i386 architectures, the int type has only 32 bits, meaning MSISDNs overflowed this. This PR fixes this by changing its type to int64. The struct is mainly used for unmarshalling responses so you likely need not worry about this.

Error handling

The way errors are handled changes significantly in v5.

Before, the errors returned by the MessageBird API would be included in the resulting resource. You would do this (ignoring the change to the package structure, as described above):

balance, err := balance.Read(client)
if err != nil && err == messagebird.ErrResponse {
    for _, mbError := range balance.Errors {
        // Do something with mbError.
    }
}

Starting with v5, errors from the MessageBird API also implement the error interface. They are no longer defined on the resources, but instead returned as you're used to from most Go code (its last return value).

It looks like this:

balance, err := balance.Read(client)
if err != nil {
    // Print a generic error message.
    log.Printf("%s\n", err)

    // Or inspect individual errors:
    switch errResp := err.(type) {
    case messagebird.ErrorResponse:
        for _, mbError := range errResp.Errors {
            log.Printf("%d: %s in %s", mbError.Code, mbError.Description, mbError.Parameter)

            // Implements `error` as well...
            log.Printf("%s\n", mbError)
        }
    }
}

Other improvements

Although those are all breaking changes, it's worth mentioning this new version brings a number of other improvements. An example is that the client now supports contacts and groups - enjoy!

v5.5.0 -> v6.0.0

Version suffix

To preserve import compatibility, the go command requires that modules with major version v2 or later use a module path with that major version as the final element.

So all imports of go-rest-api are replaced as go-rest-api/v6.

v6.1.0 -> v7.0.0

Verify Recipient type

As v7 introduces support for using the Verify API with email recipients, the Verify.Recipient field has been changed from to a string type.

v7.1.0 -> v8.0.0

Update SMS API

Added missed fields in SMS API. Updated sms.Delete method so now in return only error or nil as result.

v8.0.0 -> v9.0.0

General

  • New PaginationRequest instead of many in APIs.
  • New interface messagebird.Client and messagebird.DefaultClient instead of old implementation messagebird.Client and new MockClient for better testing.
  • List structures now have a plural ending instead of using word "List". Example: ContactList -> Contacts.
  • conversations.ConversationStatus replaced by conversations.Status.
  • number.NumberPattern replaced by number.SearchPattern.
  • Added Partner Accounts API.

Conversations API

  • Replaced conversations.CreateMessage with conversations.Reply which send a new message to an existing conversation.
  • Replaced conversations.ListMessages with conversations.ListConversationMessages which fetch messages in indicated conversation.
  • Added conversations.SendMessage to send a message to a specific recipient in a specific platform.
  • Added conversations.ListByContact to retrieves the list of conversation IDs of a specific contact ID.
  • Now conversations.ListMessages retrieves a list of messages given a list of message IDs or a timestamp (not both).