Category: Development

This release continues to clean up the API and correct some of the design issues introduced during the addition of new item types. Forecasting and budgeting will be making their way to the API soon, it makes sense to simplify some of the unnecessary abstractions that crept in. The forecasting and budgeting system will not behave in the same way as traditional expenses so it doesn’t make sense to try and adapt the system I had, rather allow there to be differences between all the item types.

There are 11 development stories (more will be created) and the rest of the tests to write, the API will then be ready to ship, well, the soft release will be ready. The API is not officially ready until the documentation has been moved away from Postman and budgeting forecasting support exists, either way it will be a massive milestone for us.

After that, I move towards getting the App to the same stage, soft release. When the App and API are at the same milestone, development begins on forecasting and budgeting, there might be a small intermission whilst I build another app but that can be thought of a proof of concept for the budgeting.

The next four months are going to be full-on, all we can do is see where we are in September and go from there.

Added

• We have added our first schema files for OPTIONS responses and started working on the tests.
• We have added tests for category management, found one bug when creating the tests.

Changed

• We have updated our response class for OPTIONS responses, we now allow parameters to be defined for POST requests. One example of where we need this is the create password POST request, password and password_confirmation are required fields, however, token and email are required parameters. Before this update, you had to parse the returned error of read the OPTIONS request description.
• We have started splitting config files, a config file should be for one purpose.
• We have spent quite a bit of time reviewing the API structure and refactoring. We have removed unnecessary complexity, renamed classes and methods to describe intent more clearly and removed pointless base classes.
• We have reworked how allowed values are generated for the different item types, allowed values for fields and parameters have been split, and we have removed all abstraction.
• We have removed some route validation files which didn’t do anything useful after all the item type work.
• We have reworked the responses class, removed exception parameters when not necessary, pass in an exception if thrown and now delegated responsibility to the responses class to decide if the exception should be returned in the response.
• We have upgraded the API to Laravel 9 and PHP 8.1.

Fixed

• Options request incorrect for the auth.register endpoint (Test added).
• Options requests returning response twice.
• Type corrected in OPTIONS response, authentication status/requirements now a boolean, not a string.
• Minor correction to the description of two POST endpoints.
• Corrected a type in the OPTIONS response for the month parameter.
• Corrected the partial-transfer JSON schema file.
• Allowed values not showing for category on GET endpoints.
• Inconsistent usage of the responses helper.
• Category validator allowed duplicate names due to incorrect params, caught by model.

Removed

• We have removed the ItemType base class and all the child classes.
• We have removed a redundant validation class and moved the response method into the main response class.

We aren’t sure how it happened, but we ended up with the feature tests for the Costs to Expect API being a Postman collection. There are over four hundred requests in the test collection and thousands of assertions are run on the responses, somewhere in the region of three thousand.

We like Postman, we use it every day. We use Postman for development and our documentation, public and private. You can view the documentation for the Costs to Expect API at https://postman.costs-to-expect.com

We have come to the realisation, much too late, that testing is not something we should be doing in Postman. We have started moving/recreating our feature tests, we have opted for local PHPUnit tests.

Recreating our tests will be a slow process, every new release will include tests, however, we are not focusing on just tests. “Why?” you ask. Well, we have tests, they simply aren’t ideal.

We are aiming to have our local tests in place as soon as possible, as much as that is our goal, we must be realistic, we simply can’t justify spending weeks writing new tests when we have a suite of working tests.

Moving to local tests is paying off already. In the latest release, we improved the first-install process for the API and made the code more testable. These improvements are a direct result of moving to local tests.

We have added a section to the README detailing our progress. We don’t want this section to exist in the README for too long so will ensure we add a decent number of useful tests each release.

We have made a number of fixes and tweaks, the changes can be seen below.

Changed

• We have added named section links, you will be taken to the relevant data, not the top of a page.
• We have updated our back-end dependencies.
• We have added ‘expires’ to the “API Requests” table shown at the bottom on each page.

Fixed

• With have fixed a small issue where the menu was not highlighting the active menu item.
• We have updated the summary layouts for mobile devices; the summary counts have a little more breathing room.
• We have increased our minimum TTL to 30 days. The one-day TTL was making a mockery of our asynchronous group requests when one or more requests return an empty response.
• We have corrected an issue with our create resource forms; the ‘effective_date’ field HTML was malformed.
• When you copy an expense of type ‘allocated-expense’, the effective date is copied.

In this release, we add the X-Last-Updated header to many more routes. We are going to conditionally cache responses in the Costs to Expect App and need to know the last time the content changed, one day we will use the etag.

Changed

• We have added the X-Last-Updated header to the resource-types, resources, categories, subcategories, items and resource items collection routes.
• We have added the X-Last-Updated header to additional summary routes; the header was missing, and we are going to use it.
• We have increased the coverage of our request test suite.
• We have relocated our Transformer classes; we have moved them out of the Models namespace.

Fixed

• We have updated the way we calculated the value for X-Last-Updated. We are using the max of the created at and updated at, not just looking at the created at time.

In this release, we rework our item controllers, add a `complete` filter for the `game` item-type and reorganise all item-type classes.

Added 

• We have added a `complete` parameter for the `game` item-type; when the parameter is included and set to true, only complete games will be returned in collections and summaries.

Changed

• We have added item-type based response classes for all item collections and summaries. Item and resource type items are unique; there are no shared dependencies. The shared dependencies were a result of the first two item-types being similar, with the addition of the game item-type, we have learnt our lesson.
• We have tweaked the TTL for permitted, and viewable resource types. The TTL for public viewable resource types is higher than for private users.
• With the addition of more item-type classes, we have tweaked our collection TTLs for public and private users.
• We have moved our ‘Method’ classes; it doesn’t make sense for them to sit inside the ‘Option’ namespace.
• We have moved our ‘AllowedValue’ classes; it doesn’t make sense for them to sit inside the ‘Option’ namespace.
• We have reorganised all the item-type classes; we are keeping all the classes for each item-type together.
• We have tweaked our response classes; we will do slightly less work when reading from the cache.

Removed

• We have removed all our interfaces; the interfaces were not useful, and we are going a slightly different way with the item-type classes, interfaces will return.

In this release, we continue our long-term task of ensuring the API can handle all the different item-types we have planned. The initial version of the API focused on expenses; slowly, we are adjusting the API to a more modular system.

Added

• We are now locally caching the permitted and viewable resource types; this change means we can skip a more expensive query per API request whilst the response is cached, we are experimenting with the TTL.

Changed

• We have added item name and description fields to the partial-transfers collection.
• We have updated the schema for partial-transfers.
• We have updated the game item-type; the winner field will now be null or an object, the object will have an id and a name.
• We have updated the OPTIONS request for the game item-type; the allowed values for the winner field will display if necessary.
• We have tweaked our middleware; we use our Hash class rather than duplicating the effort.
• We have created several new classes to generate the allowed values data; these new classes are specific to each of our supported item-type. This change will speed up the OPTIONS requests for the non allocated-expense item type as we will no longer query the database when we know there will be no results.
• We have added a check to limit access to the partial-transfers route. The ‘allocated-expense’ item-type supports the partial-transfers feature, partial-transfers don’t make sense for the other item-types.
• We have drastically simplified route validation. The API controls access to resources at the resource type level; we have updated all route checks to validate the requested resource type rather than validate specific access to the request entity.

Fixed

• We have corrected several configuration file calls; our calls were looking at transfers, not partial transfers.
• We have added localisation files for the simple-item and game item-type, several were missing.

In this release, we add the dashboards for our new board, card and dice game tracking feature. The feature isn’t quite complete; we introduced a couple of issues in the last release so needed to ship early.

Added

• We have updated the main dashboard; our main dashboard supports the game item-type.
• We have added the resource level game item-type dashboard.
• We have added the resource-type level game item-type dashboard.
• We have added a toggle to allocated-expense item-type tables; you an optionally include unpublished expenses in the tables.
• We have added the effective date for an allocated-expense to the item detail page.

Changed

• We have updated our error messages; our messages will provide a little more detail.
• We have updated our no-resource view helpers; the help message we display will be specific to the item-type selected when creating the resource type.
• We have updated our create, delete and edit resource forms; at the resource level, we know the selected item type, we have customised the language to match the item type.
• We have updated our delete and edit resource type forms; we know the selected item type so have customised the language to match the item type.
• We have added item subtype support for all our item forms; the App is aware of the resource subtype and loads the form based on the selected item subtype.

Fixed

• We have fixed the URIs to fetch resource types and resources, there was a rogue question mark for the limit parameter.
• We have fixed an issue with our copy and edit item forms; the App was unable to preselect the category and subcategory.

In this release, we correct a minor cache issue and add extra information to resource type objects.

Changed

• We have updated the friendly_name for item types; the updated names provide more information and make customising the App simpler.
• We have updated the item-type object included within the resource type object; the item-type object will include the friendly_name field.
• We have updated the description for our game item type; we are going to support dice games.
• We have removed the duplicated includeUnpublished functions and added a reusable method to our Clause class.
• We have disabled sessions for our web routes.

Fixed

• We have corrected an issue with our cache; we were incorrectly creating public cache entries rather than private cache entries. No data is leaking because the cache for resource types controls access and the resource type cache is correct.
• We have renamed the method which adds the clause to include unpublished costs. By default, the method excludes unpublished expenses, so we renamed the method to make the intention clear.

In this release, we add initial support for our new feature, Board and Card game scoring. We expect there will be a couple of point updates as we develop the rest of the new feature in the Costs to Expect App.

Added

• We have added a migration to create the `game` item-type table.
• We have added the configuration for the `game` item-types.
• We have added a schema for the `game` item-type.
• We have added a schema for the `game` resource type item-type.
• We have updated the item and resource type item collections; the collections are aware of the new `game` item-type.
• We have updated the summary routes; the item and resource type item summaries are aware of the new `game` item-type.

Changed

• We are upgrading summaries; the new `game` summaries include much more information than other summaries. We will upgrade all the summaries a little bit at a time.

Fixed

• We have removed a rogue validation rule present in the POST request for the `allocated-expense` item type.
• We have updated the item category and subcategory assignment routes. Category and subcategory assignment routes can show more than one item in the collection if the item-type configuration allows.