Dart Sass with Windows Linux Subsystem

Follow the steps below to setup sass, specifically dart-sass in the Windows Linux Subsystem.

  1. Download and extract the dart-sass release you are going to use, at the time of this post I opted for dart-sass-1.18.0-linux-x64.tar.gz
  2. Find your bash.rc, if you setup WLSS after the Fall Creators update it will be located at C:\Users\USERNAME\AppData\Local\Packages\{CanonicalGroupLimited.UbuntuonWindows_...}\LocalState\rootfs\home\LINUXUSER\ or similar.
  3. Add export PATH="/path/to/dart-sass:$PATH" to the end of the file, in my case export PATH="/mnt/c/Users/USERNAME/Documents/GitHub/dart-sass:$PATH"

Open bash, type sass --version to see if everything worked.

Where to put summary routes in your API?

I believe the response to the question is going to be different for every API, in my case I initially added them where I thought it made sense, at the level I thought I wanted to summarise.

To view the list of items assigned to a resource in the Costs to Expect API you browse as below;
/resource-type/[id]/resource/[id]/items.
To view the TCO (Total cost of ownership) for a resource, I added a summary route at /resource-type/[id]/resource/[id]/summary/tco.

This initially made sense, however, later, as I was adding year and month summaries my solution began to become unwieldy, longterm, I would end up with two mismatching trees, the main tree for the API and then another summary tree, secondly, using this structure, where would I put a summary for multiple resources?

I’ve come up with a solution that I think will solve my problems, there should be a summary route for every API endpoint, the summary routes are then merely the route prefixed with /summary.

In the case of the TCO for a resource, the summary route would be summary/resource-type/[id]/resource/[id]/items. No TCO in the URI, it is not necessary, you are summarising the items collection so you should expect a total.

My solution doesn’t fix all the issues, presently the annual summary for a resource lives at /resource-type/[id]/resource/[id]/summary/years. There is no matching endpoint for this summary route. The solution, GET parameters. The items collection has four filtering parameters, year, month, category and subcategory; the summary route should support the same parameters.

I’m confident that if I had spent a little more time researching I would have been able to find this solution in an article somewhere online, I didn’t and unfortunately, it took me a little while to realise. Hopefully, this blog post will help at least one other person.

Do not change URIs, oops

A core rule of the Internet, don’t change a URI. I’m going to change some, why, we all make mistakes.

I released the initial version of the Costs to Expect API during the summer of ’18. It turns out when you review your code/API after a short break you spot all the issues you were oblivious to during development.

Over the next 12 months, I’m going to extend the Costs to Expect API, an API that I intend on maintaining for a significant period; I need to record data for at least the next 13 years.

If there were one small issue with the URIs, I’d deal with it, change a couple of URIs and add redirects. There are numerous issues; I am not happy with the initial summary routes. I favour dashes in the URIs over underscores, some of the words are incorrect and other minor issues.

We haven’t pushed the service; it doesn’t exist. As far as I am aware I am the only consumer of the API. I believe it is OK to modify the URIs, as long as I do not modify them again they should remain the same for twenty times longer then they have existed.

Self-documenting APIs

During my professional career I’ve worked on many APIs, however, I’ve never been responsible for the design, development and support of an API of more than trivial scale, when designing my own I wanted to do ‘as good of a job’ as I possibly can.

I’ve heard the term self-documenting APIs and never really looked into it, regardless, I’m going to describe what it means to me, hey, it is the internet, we all have opinions.

To me, there are five points.

  • The initial entry route or an obviously named route should display all the endpoints.
  • The initial entry route or an obviously named route should show the current version of the API as well as provide links to the README, CHANGELOG and anything else useful.
  • There should be a changelog route to describe all changes and updates to the API.
  • An OPTIONS request should exist for every route. The OPTIONS request should detail the purpose of the route, all possible verbs, as well as any fields and parameters.
  • No redundant information in either the payload or the response, for example, the payload should not be wrapped in an envelope, the verb is the envelope.

As a bonus, API versioning should be controlled via the route, any payloads or responses should be free of any version information.

OPTIONS requests

When I published the Costs to Expect API I was initially bemused, none of my OPTIONS requests worked, they all return “405 method not allowed”.

After searching, I diagnosed the problem. The HTTP OPTIONS request fails because the default PHP-CGI handler does not handle the “OPTIONS” verb.

The fix is simple, update or add the handler in web.config.

<handlers>
<remove name=”PHP72_via_FastCGI” />
<add name=”PHP72_via_FastCGI” path=”*.php” verb=”GET,PUT,POST,DELETE,HEAD,OPTIONS” modules=”FastCgiModule” scriptProcessor=”PATH\To\File\php-cgi.exe” resourceType=”Either” requireAccess=”Script” />
</handlers>

Reduced development time :(

As I have mentioned before, I’m lucky enough to be able to take time off during the year to work on my projects, every time I take on a new contract my schedule goes out of whack.

When I’m not contracting, outside of real life commitments, I try to dedicate as many as 30hrs per week to work on my projects, when I’m contracting that isn’t possible, a 40hr week with travel doesn’t leave much free time.

The last two weeks have been an adjustment, I managed to log 5.5hrs the first week and 7.5hrs the second week, I’m on track for 10hrs this week.

Is this a real problem, no, the first world called and wants a tissue, the issue is expectations, during my summer off I steamed through my work, with reality hitting, productivity takes a nosedive. Eventually, Pivotal Tracker will update to show more accurate completion times; once I’m three sprints in, until then, it is frustrating looking at completion dates that are optimistic.

Why am I blogging about this? As the site byline says, I was musing.

Releasing…works

I have a long-term project, Dlayer, that I very much believe in, but after many false starts, it still doesn’t exist, it will though, I’m due to restart it later this year with a slightly different focus 🙂

Why did I never finish or release the project? I never managed to hit what I considered to be the minimum viable product (MVP), my idea of the MVP for Dlayer was too vast, and far too much for one developer, I never managed to get enough done.

Early last year I needed to develop a small library, my PHP Quill renderer, I developed just what I needed at the time and quickly released it, within six months I bumped it to v1.00. I knocked it to v1.00 because I was confident in the library, it had warts, but people seemed to be using it, it wasn’t just solving my personal problem.

I’m not suggesting tagging it with a v1.00 release number made it slightly popular, I’m saying that because I was confident enough to add the v1.00 release number it became more popular.

Tagging the library with v1.00 meant I had to handle it differently, I needed to ensure the README and CHANGELOG were accurate, and up to date, tests are required, and I needed to learn how to handle the pull requests I started receiving. All of this made the library better, as I’ve said in the past, nothing makes your code better than knowing there is a minuscule chance other developers will look at your library.

During the summer I released two apps, both v1.00, the REST API for Costs to Expect and the companion Web app. Neither of these apps is complete. The REST API is missing quite a few features; however, it supports enough to get the job done, replace my spreadsheet and allow my wife to submit data.

I’m not saying anything new; there is a blog post by Jeff Atwood referencing a blog post by Chuck Jazdzewski stating our job is to ship. Knowing that is one thing, doing it is another, I wish I had had the confidence to ship earlier, and I hope I keep it up.

Costs to Expect API

The Costs to Expect API is ready for release*.

I’m going to continue development to add additional features and start working on the summary endpoints and endpoints required for the companion website, however, the API itself could be released today.

The API is ready, five years and two months of child costs exist, the two need to be put together.

I’m going to work with my Wife to review and categorise the data. Our data is categorised, however, for the API we want to break the data down a little more, our data is split into thirteen categories, we intend to have fewer base categories and subcategories to provide the detail.

*I’m not setting a release date, it will be soon though, I want to get the API out before I look for a new contract and go back to work.

Once the API is out, I will start development on the companion website for data input (preview for iOS app), the iOS app and the website to display the data.

We have several long-term plans for the Costs to Expect API and website, one being to allow additional data, for example, localised costs for childcare/hobbies etc. Our intention is you will be able to augment our base data to get a more accurate idea.

Summer off, what does off really mean?

As a contract developer, I’m lucky enough to have I have the luxury of choosing when not to work, I’ve just finished a six-month contract and rather than find a new contract immediately I am taking the summer off to work on my projects.

I have many personal projects, the big one that dates back years and then lots of small projects, one of which has become far more popular than I ever expected and is keeping me busy.

What does a summer off mean?

Outside of social and family commitments, it means I have a bit more time to focus on my projects. I always manage to find time to work on my projects, being a night owl, but it is nice to have the extra time, makes it easier to solve the more significant problems that you can’t entirely get your head around when you only have a couple of hours at the end of a long day.

In no particular order, I am going to support and improve my open source projects, learn Swift, write a simple app to interface with a RESTful API, develop the API and if I get time, work on my long-term project and do some charting and graphing work for a new website.

The above is a tall order for six to eight weeks; we will see in September/October how far I got.

Open Source is awesome, PHP Quill Renderer v3.01.0

A few hours after arriving at work I got an email from GitHub letting me know about a posted issue on one of my Open Source libraries, turns out I had missed a couple of things in my testing.

When I create a library, I have a use case in mind; typically I’m trying to solve a problem specific to one of my projects, having an extra set of eyes reviewing my libraries and using them differently is terrific.

I’m always happy to receive bug reports; each fix improves the library. Hopefully, there will not be too many more but if there are I will jump on them to fix the issue.

I have released v3.01.0 of my PHP Quill Renderer; Parser::load() wasn’t resetting the deltas array, and the Compound delta was incorrectly trying to handle images with multiple attributes assigned.