Merge pull request #47 from messagebird/v5_staging

V5 staging

Author: epels

README.md

@@ -36,16 +36,16 @@ Now you can query the API for information or send data. For example, if we want
 
 ```go
 // Request the balance information, returned as a Balance object.
-balance, err := client.Balance()
+balance, err := balance.Read(client)
 if err != nil {
-  // messagebird.ErrResponse means custom JSON errors.
-  if err == messagebird.ErrResponse {
-    for _, mbError := range balance.Errors {
-      fmt.Printf("Error: %#v\n", mbError)
-    }
-  }
-
-  return
+	switch errResp := err.(type) {
+	case messagebird.ErrorResponse:
+		for _, mbError := range errResp.Errors {
+			fmt.Printf("Error: %#v\n", mbError)
+		}
+	}
+
+	return
 }
 
 fmt.Println("  payment :", balance.Payment)
@@ -68,6 +68,10 @@ Documentation
 Complete documentation, instructions, and examples are available at:
 [https://developers.messagebird.com](https://developers.messagebird.com).
 
+Upgrading
+---------
+If you're upgrading from older versions, please read the [Messagebird `go-rest-api` uprading guide](UPGRADING.md).
+
 License
 -------
 The MessageBird REST Client for Go is licensed under [The BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause). Copyright (c) 2014, 2015, MessageBird

UPGRADING.md

@@ -0,0 +1,94 @@
+# 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:
+```go
+client := messagebird.New("YOUR_ACCESS_KEY")
+balance, err := client.Balance()
+
+// ...
+```
+
+After:
+```go
+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](https://blog.golang.org/package-names), 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](https://github.com/messagebird/go-rest-api/pull/19) 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):
+
+```go
+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:
+
+```go
+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!

balance.go

@@ -0,0 +1,27 @@
+package balance
+
+import (
+	"net/http"
+
+	messagebird "github.com/messagebird/go-rest-api"
+)
+
+// Balance describes your balance information.
+type Balance struct {
+	Payment string
+	Type    string
+	Amount  float32
+}
+
+const path = "balance"
+
+// Read returns the balance information for the account that is associated with
+// the access key.
+func Read(c *messagebird.Client) (*Balance, error) {
+	balance := &Balance{}
+	if err := c.Request(balance, http.MethodGet, path, nil); err != nil {
+		return nil, err
+	}
+
+	return balance, nil
+}

balance/balance.go

@@ -1,43 +1,52 @@
-package messagebird
+package balance
 
-import "testing"
+import (
+	"net/http"
+	"testing"
 
-var balanceObject = []byte(`{
-  "payment":"prepaid",
-  "type":"credits",
-  "amount":9.2
-}`)
+	messagebird "github.com/messagebird/go-rest-api"
+	"github.com/messagebird/go-rest-api/internal/mbtest"
+)
 
 const Epsilon float32 = 0.001
 
 func cmpFloat32(a, b float32) bool {
 	return (a-b) < Epsilon && (b-a) < Epsilon
 }
 
-func TestBalance(t *testing.T) {
-	SetServerResponse(200, balanceObject)
+func TestMain(m *testing.M) {
+	mbtest.EnableServer(m)
+}
+
+func TestRead(t *testing.T) {
+	mbtest.WillReturnTestdata(t, "balance.json", http.StatusOK)
+	client := mbtest.Client(t)
 
-	balance, err := mbClient.Balance()
+	balance, err := Read(client)
 	if err != nil {
 		t.Fatalf("Didn't expect error while fetching the balance: %s", err)
 	}
 
 	if balance.Payment != "prepaid" {
 		t.Errorf("Unexpected balance payment: %s", balance.Payment)
 	}
+
 	if balance.Type != "credits" {
 		t.Errorf("Unexpected balance type: %s", balance.Type)
 	}
+
 	if !cmpFloat32(balance.Amount, 9.2) {
 		t.Errorf("Unexpected balance amount: %.2f", balance.Amount)
 	}
 }
 
-func TestBalanceError(t *testing.T) {
-	SetServerResponse(405, accessKeyErrorObject)
-	_, err := mbClient.Balance()
+func TestReadError(t *testing.T) {
+	mbtest.WillReturnAccessKeyError()
+	client := mbtest.Client(t)
+
+	_, err := Read(client)
 
-	errorResponse, ok := err.(ErrorResponse)
+	errorResponse, ok := err.(messagebird.ErrorResponse)
 	if !ok {
 		t.Fatalf("Expected ErrorResponse to be returned, instead I got %s", err)
 	}

balance_test.go renamed to balance/balance_test.go

@@ -0,0 +1,5 @@
+{
+    "payment": "prepaid",
+    "type": "credits",
+    "amount": 9.2
+}