feat!: budgets with new API layout (#140)

Author: morremeyer

docs/api.md

@@ -2,7 +2,14 @@
 
 This document contains the API design. It is aimed at developers and to support administrators in debugging issues.
 
-## API Responses
+## High level guarantees
+
+- Any resource will be available at the endpoints `/{resource}` for the collection and `/{resource}/{id}` for a single resource.
+- Filtering on collection endpoints is implemented with URL paramaters (“query strings“)
+- Collections always support the HTTP methods `GET` (read resources) and `POST` (create new resource)
+- Resources support the HTTP methods `GET` (read resource), `PATCH` (update resource) and `DELETE` (delete resource)
+
+## API responses
 
 All API responses either have an emty body (for HTTP 204 and HTTP 404 responses) or the body consists of only JSON.
 
@@ -12,13 +19,15 @@ The `error` key always has a value of type `string`, containing a human readable
 
 The `data` key is either a list of objects (for collection endpoints) or a single object (for resource endpoints).
 
-Unset attributes are not contained in the objects that the API returns. Unless an attribute is defined in here to be always contained in API responses, it is optional
+Unset attributes are not contained in the objects that the API returns. Unless an attribute is defined in here to be always contained in API responses with tse string `Always present`, it is optional.
 
-### Reserved keys
+## API resources
 
-The objects in the `data` key have several reserved keys that are read-only:
+API resources share the following **read only** attributes in the `data` key:
 
-- `createdAt`: An RFC3339 timestamp of the time when the resource was created. Always present.
-- `updatedAt`: An RFC3339 timestamp of the time when the resource was updated. Always present.
-- `deletedAt`: An RFC3339 timestamp of the time when the resource was deleted.
-- `id`: The ID of the object. IDs are unique for the backend instance. Always present.
+- `createdAt` (string): An RFC3339 timestamp of the time when the resource was created. Always present.
+- `updatedAt` (string): An RFC3339 timestamp of the time when the resource was updated. Always present.
+- `deletedAt` (string): An RFC3339 timestamp of the time when the resource was deleted.
+- `id` (number): The ID of the object. IDs are unique for the backend instance. Always present.
+- `links` (object): A map of related resources. Always present.
+  - `self` (string): The full URL of the resource itself. Always present.

internal/controllers/account.go

@@ -69,7 +69,7 @@ func OptionsAccountDetail(c *gin.Context) {
 }
 
 // @Summary      Create account
-// @Description  Create a new account for a specific budget
+// @Description  Create a new account
 // @Tags         Accounts
 // @Produce      json
 // @Success      201  {object}  AccountResponse
@@ -86,7 +86,7 @@ func CreateAccount(c *gin.Context) {
 	}
 
 	// Check if the budget that the account shoud belong to exists
-	_, err := getBudget(c, account.BudgetID)
+	_, err := getBudgetResource(c, account.BudgetID)
 	if err != nil {
 		return
 	}
@@ -98,7 +98,7 @@ func CreateAccount(c *gin.Context) {
 }
 
 // @Summary      List accounts
-// @Description  Returns a list of all accounts for the budget
+// @Description  Returns a list of all accounts
 // @Tags         Accounts
 // @Produce      json
 // @Success      200  {object}  AccountListResponse
@@ -109,7 +109,7 @@ func CreateAccount(c *gin.Context) {
 func GetAccounts(c *gin.Context) {
 	var accounts []models.Account
 
-	models.DB.Where(&models.Account{}).Find(&accounts)
+	models.DB.Find(&accounts)
 
 	// When there are no accounts, we want an empty list, not null
 	// Therefore, we use make to create a slice with zero elements
@@ -237,7 +237,7 @@ func getAccountObject(c *gin.Context, id uint64) (Account, error) {
 
 // getAccountLinks returns an AccountLinks struct.
 //
-// This function is only needed for newAccountResponse as we cannot create an instance of Account
+// This function is only needed for getAccountObject as we cannot create an instance of Account
 // with mixed named and unnamed parameters.
 func getAccountLinks(c *gin.Context, id uint64) AccountLinks {
 	url := httputil.RequestPathV1(c) + fmt.Sprintf("/accounts/%d", id)

internal/controllers/account_test.go

@@ -42,11 +42,8 @@ func TestGetAccounts(t *testing.T) {
 	assert.Equal(t, true, externalAccount.External)
 
 	for _, account := range response.Data {
-		diff := time.Now().Sub(account.CreatedAt)
-		assert.LessOrEqual(t, diff, test.TOLERANCE)
-
-		diff = time.Now().Sub(account.UpdatedAt)
-		assert.LessOrEqual(t, diff, test.TOLERANCE)
+		assert.LessOrEqual(t, time.Since(account.CreatedAt), test.TOLERANCE)
+		assert.LessOrEqual(t, time.Since(account.UpdatedAt), test.TOLERANCE)
 	}
 
 	if !decimal.NewFromFloat(-30).Equal(bankAccount.Balance) {

internal/controllers/allocation_test.go

@@ -41,11 +41,8 @@ func TestGetAllocations(t *testing.T) {
 		assert.Fail(t, "Allocation amount does not equal 20.99", response.Data[0].Amount)
 	}
 
-	diff := time.Now().Sub(response.Data[0].CreatedAt)
-	assert.LessOrEqual(t, diff, test.TOLERANCE)
-
-	diff = time.Now().Sub(response.Data[0].UpdatedAt)
-	assert.LessOrEqual(t, diff, test.TOLERANCE)
+	assert.LessOrEqual(t, time.Since(response.Data[0].CreatedAt), test.TOLERANCE)
+	assert.LessOrEqual(t, time.Since(response.Data[0].UpdatedAt), test.TOLERANCE)
 }
 
 func TestNoAllocationNotFound(t *testing.T) {

internal/controllers/budget.go

@@ -12,15 +12,20 @@ import (
 )
 
 type BudgetListResponse struct {
-	Data []models.Budget `json:"data"`
+	Data []Budget `json:"data"`
 }
 
 type BudgetResponse struct {
-	Data  models.Budget `json:"data"`
-	Links BudgetLinks   `json:"links"`
+	Data Budget `json:"data"`
+}
+
+type Budget struct {
+	models.Budget
+	Links BudgetLinks `json:"links"`
 }
 
 type BudgetLinks struct {
+	Self         string `json:"self" example:"https://example.com/api/v1/budgets/4"`
 	Accounts     string `json:"accounts" example:"https://example.com/api/v1/accounts?budget=2"`
 	Categories   string `json:"categories" example:"https://example.com/api/v1/budgets/2/categories"`
 	Transactions string `json:"transactions" example:"https://example.com/api/v1/budgets/2/transactions"`
@@ -88,14 +93,16 @@ func OptionsBudgetDetail(c *gin.Context) {
 // @Param        budget    body      models.BudgetCreate  true  "Budget"
 // @Router       /v1/budgets [post]
 func CreateBudget(c *gin.Context) {
-	var data models.Budget
+	var budget models.Budget
 
-	if err := httputil.BindData(c, &data); err != nil {
+	if err := httputil.BindData(c, &budget); err != nil {
 		return
 	}
 
-	models.DB.Create(&data)
-	c.JSON(http.StatusCreated, BudgetResponse{Data: data})
+	models.DB.Create(&budget)
+
+	budgetObject, _ := getBudgetObject(c, budget.ID)
+	c.JSON(http.StatusCreated, BudgetResponse{Data: budgetObject})
 }
 
 // @Summary      List all budgets
@@ -109,9 +116,17 @@ func GetBudgets(c *gin.Context) {
 	var budgets []models.Budget
 	models.DB.Find(&budgets)
 
-	c.JSON(http.StatusOK, BudgetListResponse{
-		Data: budgets,
-	})
+	// When there are no budgets, we want an empty list, not null
+	// Therefore, we use make to create a slice with zero elements
+	// which will be marshalled to an empty JSON array
+	budgetObjects := make([]Budget, 0)
+
+	for _, budget := range budgets {
+		o, _ := getBudgetObject(c, budget.ID)
+		budgetObjects = append(budgetObjects, o)
+	}
+
+	c.JSON(http.StatusOK, BudgetListResponse{Data: budgetObjects})
 }
 
 // @Summary      Get a budget
@@ -125,12 +140,17 @@ func GetBudgets(c *gin.Context) {
 // @Param        budgetId  path      uint64  true  "ID of the budget"
 // @Router       /v1/budgets/{budgetId} [get]
 func GetBudget(c *gin.Context) {
-	_, err := getBudgetResource(c)
+	id, err := httputil.ParseID(c, "budgetId")
+	if err != nil {
+		return
+	}
+
+	budgetObject, err := getBudgetObject(c, id)
 	if err != nil {
 		return
 	}
 
-	c.JSON(http.StatusOK, newBudgetResponse(c))
+	c.JSON(http.StatusOK, BudgetResponse{Data: budgetObject})
 }
 
 // @Summary      Get Budget month data
@@ -145,7 +165,12 @@ func GetBudget(c *gin.Context) {
 // @Param        month     path      string  true  "The month in YYYY-MM format"
 // @Router       /v1/budgets/{budgetId}/{month} [get]
 func GetBudgetMonth(c *gin.Context) {
-	budget, err := getBudgetResource(c)
+	id, err := httputil.ParseID(c, "budgetId")
+	if err != nil {
+		return
+	}
+
+	budget, err := getBudgetResource(c, id)
 	if err != nil {
 		return
 	}
@@ -160,9 +185,21 @@ func GetBudgetMonth(c *gin.Context) {
 		return
 	}
 
-	envelopes, err := getEnvelopeResources(c)
-	if err != nil {
-		return
+	var envelopes []models.Envelope
+
+	categories, _ := getCategoryResources(c, budget.ID)
+
+	// Get envelopes for all categories
+	for _, category := range categories {
+		var e []models.Envelope
+
+		models.DB.Where(&models.Envelope{
+			EnvelopeCreate: models.EnvelopeCreate{
+				CategoryID: category.ID,
+			},
+		}).Find(&e)
+
+		envelopes = append(envelopes, e...)
 	}
 
 	var envelopeMonths []models.EnvelopeMonth
@@ -191,7 +228,12 @@ func GetBudgetMonth(c *gin.Context) {
 // @Param        budget  body      models.BudgetCreate  true  "Budget"
 // @Router       /v1/budgets/{budgetId} [patch]
 func UpdateBudget(c *gin.Context) {
-	budget, err := getBudgetResource(c)
+	id, err := httputil.ParseID(c, "budgetId")
+	if err != nil {
+		return
+	}
+
+	budget, err := getBudgetResource(c, id)
 	if err != nil {
 		return
 	}
@@ -202,7 +244,8 @@ func UpdateBudget(c *gin.Context) {
 	}
 
 	models.DB.Model(&budget).Updates(data)
-	c.JSON(http.StatusOK, newBudgetResponse(c))
+	budgetObject, _ := getBudgetObject(c, budget.ID)
+	c.JSON(http.StatusOK, BudgetResponse{Data: budgetObject})
 }
 
 // @Summary      Delete a budget
@@ -215,41 +258,23 @@ func UpdateBudget(c *gin.Context) {
 // @Param        budgetId  path      uint64  true  "ID of the budget"
 // @Router       /v1/budgets/{budgetId} [delete]
 func DeleteBudget(c *gin.Context) {
-	budget, err := getBudgetResource(c)
+	id, err := httputil.ParseID(c, "budgetId")
 	if err != nil {
 		return
 	}
 
-	models.DB.Delete(&budget)
-
-	c.JSON(http.StatusNoContent, gin.H{})
-}
-
-// getBudgetResource verifies that the budget from the URL parameters exists and returns it.
-func getBudgetResource(c *gin.Context) (models.Budget, error) {
-	var budget models.Budget
-
-	budgetID, err := httputil.ParseID(c, "budgetId")
+	budget, err := getBudgetResource(c, id)
 	if err != nil {
-		return models.Budget{}, err
+		return
 	}
 
-	// Check that the budget exists. If not, return a 404
-	err = models.DB.Where(&models.Budget{
-		Model: models.Model{
-			ID: budgetID,
-		},
-	}).First(&budget).Error
-	if err != nil {
-		httputil.FetchErrorHandler(c, err)
-		return models.Budget{}, err
-	}
+	models.DB.Delete(&budget)
 
-	return budget, nil
+	c.JSON(http.StatusNoContent, gin.H{})
 }
 
-// getBudget is the internal helper to verify permissions and return an account.
-func getBudget(c *gin.Context, id uint64) (models.Budget, error) {
+// getBudgetResource is the internal helper to verify permissions and return a budget.
+func getBudgetResource(c *gin.Context, id uint64) (models.Budget, error) {
 	var budget models.Budget
 
 	err := models.DB.Where(&models.Budget{
@@ -265,19 +290,30 @@ func getBudget(c *gin.Context, id uint64) (models.Budget, error) {
 	return budget, nil
 }
 
-func newBudgetResponse(c *gin.Context) BudgetResponse {
-	// When this function is called, the resource has already been validated
-	budget, _ := getBudgetResource(c)
+func getBudgetObject(c *gin.Context, id uint64) (Budget, error) {
+	resource, err := getBudgetResource(c, id)
+	if err != nil {
+		return Budget{}, err
+	}
 
-	url := httputil.RequestPathV1(c) + fmt.Sprintf("/budgets/%d", budget.ID)
+	return Budget{
+		resource,
+		getBudgetLinks(c, resource.ID),
+	}, nil
+}
 
-	return BudgetResponse{
-		Data: budget,
-		Links: BudgetLinks{
-			Accounts:     httputil.RequestPathV1(c) + fmt.Sprintf("/accounts?budget=%d", budget.ID),
-			Categories:   url + "/transactions",
-			Transactions: url + "/transactions",
-			Month:        url + "/YYYY-MM",
-		},
+// getBudgetLinks returns a BudgetLinks struct.
+//
+// This function is only needed for getBudgetObject as we cannot create an instance of Budget
+// with mixed named and unnamed parameters.
+func getBudgetLinks(c *gin.Context, id uint64) BudgetLinks {
+	url := httputil.RequestPathV1(c) + fmt.Sprintf("/budgets/%d", id)
+
+	return BudgetLinks{
+		Self:         url,
+		Accounts:     httputil.RequestPathV1(c) + fmt.Sprintf("/accounts?budget=%d", id),
+		Categories:   url + "/categories",
+		Transactions: url + "/transactions",
+		Month:        url + "/YYYY-MM",
 	}
 }