Posts

Posted on

API endpoints, filtering, sorting, searching, limiting and summarising

The Costs to Expect API is developing slowly; features get added as I need them, v1.15.0 is an exciting release, it will be the first time an endpoint in the API can be filtered, sorted, limited, searched and summarised.

I’ve written previously about summarising collections, with the release of search in v1.15.0 it makes send to describe all options supported by the items (/v1/resource-types/[resource-type]/resources/[resource]/items) collection on the Costs to Expect API.

By default, the items collection returns all child expenses in reverse chronological order, ‘all’ and ‘reverse chronological’ are sensible defaults; however, the API is limited if the collection always returns everything, you need to be able to filter, sort, limit, search and summarise.

The Costs to Expect API supports filtering, sorting, limiting and searching via parameters appended to the URI, collections are summarised by prepending /summary/ to the URI. Summary endpoints support the same filtering and searching options as their companion collections, limiting and sorting don’t make any sense in the context of a summary.

A URI can quickly become unreadable when multiple GET parameters are assigned, to attempt and improve readability I have grouped sorting and searching.

The OPTIONS requests for the Costs to Expect API detail all the supported GET parameters, in addition to giving an overview of each parameter, the OPTIONS requests list which fields and sortable and searchable. The sort and search parameters both allow multiple conditions.

Limiting a collection is handled as expected, there is an offset parameter to define the start record and a limit parameter to define the number of records requested.

Filtering a collection is handled via individual parameters, filtering is more common than searching and in my opinion needs to be the most verbose, when reviewing a URI the filtering parameters should be more visible.

This solution won’t work for everyone; however, if you need to support filtering, searching, sorting, limiting and summarising, I think it provides an excellent level or readability while still being practical.

Posted on

Slowly developing Costs to Expect

I’m developing Costs to Expect in a slightly different manner to any of my previous large personal projects. The process is slightly different for two reasons, firstly, the design, secondly, I’m deliberately developing at a slower, more iterative pace.

Design.

There are two parts to Costs to Expect, the Open Source API and the website, the website will include the secret sauce for the service.

The API has not been explicitly written for the Costs to Expect website; the intention has always been to use it for separate projects and idealy give back to the community, hence being Open Source. So far, I have one other project that uses the API, and I have plans for another rattling around my head. I’m confident that eventually, tomorrow maybe, I will add a feature to the API specifically for the website. I intend to try and ensure features are only added to the API if they make sense in the context of the API.

Slow, iterative development.

I released the API during the summer and developed a simple app to allow my wife to enter expenses for our children; the API is not anywhere near complete, I am continually fleshing out the features priotising the features I need to develop the website, the latest example is sorting. The web app my wife uses does not require sorting, the public Costs to Expect website does; that is why I’m adding it now.

There are three initial phases of the development of the website; once all three are complete, the real project begins.

Phase 1: The website consumes the API and shows the current expenses for our children in an engaging way for public consumption.
Phase 2: My Wife is able to transition from using the web app I developed in the summer; she should be able to do the expenses management for our children using the website.
Phase 3: I develop the forecasting and budgeting systems and start opening up the website to a restricted number of test users.

I’m very much in Phase 1. I envision I have at least another four weeks of development before I can progress to Phase 2.

Phase 2 isn’t complicated; I need to ensure I make the correct decisions, I need to work out my authentication, probably oAuth, how I’m going to handle users, groups and then develop the management pages.

Phase 3 will be when the fun begins and the part I’m most looking forward to reaching. Phases 2 and 3 require time; I mostly know what is needed; I need to design and then code the systems.

The majority of my year off will be in Phase 3, I know what I need to end up with, however, I’m currently not quite sure how I’m going to get there.

For each Phase, I’m developing very slowly; the visual design is mostly solved thanks to a highly skilled designer I employed late last year, I mostly only need to think about what I need and how to develop it.

As a single developer with limited development time and resource, I can’t afford to waste any of my development time. I’m prototyping every feature and then slowly developing them, as an example, the website won’t be connecting to the API until at least v1.04.0, up until then I’ll be working on the responsive layout, building the view components I require and experimenting with the UX.