21 May
2020

Custom OpenAPI Style Rules with Spectral

Edit: There’s a newer post on this topic using Redocly CLI.

I work quite a bit with OpenAPI specs and with lots of specs and lots of collaborators, keeping the specs all functional (never mind tidy, consistent, or other dreamwords) is a challenge! We use spectral to check our specs, both when we work on them and in the build process. Spectral is great but it has Opinions(TM)!

For most users, running Spectral out of the box gives quite a lot of output even on an otherwise valid spec. I do think the default ruleset for Spectral is pretty good, but every situation is different so having your own ruleset to use is a good idea. This post shows how to use a ruleset and some examples. Continue reading →

24 Apr
2020

The `python-is-python2` package on Ubuntu Focal Fossa

I did a fresh install of Ubuntu 20.04 Focal Fossa on my laptop, and was surprised at what happened when I went to install python:

$ sudo apt install python
Reading package lists... Done
Building dependency tree       
Reading state information... Done
Note, selecting 'python-is-python2' instead of 'python'

Um, what?

It turns out that since the python package has historically been Python 2, and there’s a separate python3 package (and the commands match the package names, also pip3 etc), that default has remained in an attempt to break things for fewer people. Which is nice, but how do I get current, stable python?

sudo apt install python-is-python3

There’s a sister package called python-is-python3 and installing that makes my python command use version 3 as I expected! It’s a fairly good solution to the problem but it took me a moment to work out how to install it so I thought I’d write it down for next time! Hope it helps you too :)

15 Apr
2020

A First Netlify Function in Golang

I love all things serverless, and Netlify Functions is a neat and convenient way to access AWS Lambda. I do also love AWS Lambda but it’s so powerful and flexible that creating something like a webhook receiver can be hard going by the time you have all the permissions and API Gateway setup sorted out – for a simple webhook receiver, Netlify functions is a nice and easy way to get going. Best of all: it supports Golang but the docs are very JS-heavy so I am writing my notes here in case I need to refer back to them some day. Continue reading →
08 Apr
2020

Wget Direct to S3 with Golang Streams

One thing I find very elegant about working with golang is that it is very open minded about where data is flowing in from or going out to. I recently built an application that downloaded an audio file from one location and pushed it to s3 – and golang makes it very easy to do that without needing to write an intermediate file and then upload that. Here’s my code, in case I need to do this again some day :) Continue reading →
30 Mar
2020

HTTPMock for Testing a Golang API Client

I’m working on an API client for some Nexmo APIs and having tests to work through the various responses that the API can return and check that it does what I expect has been very handy so I thought I’d share my thoughts. I’ve got a bit of a head start here too since the OpenAPI specs have example responses in them that I can grab and feed to the mocking tool I’m using in my tests! Continue reading →
15 Mar
2020

Remove Accidental Content from Git Commit

When I teach git I try to show loads of good practice about how to inspect what’s staged before commit, etc etc. Good practice is good of course, but knowing how to undo a mess you created is better – and mistakes will happen. For example, accidentally including a node_modules directory in your otherwise excellent and useful commit. This post will walk you through how to fix the problem without losing any of your work. Continue reading →
18 Feb
2020

Teach Your API Test Platform to Send Callbacks

I already wrote about using Prism as an API test platform but I didn’t include an example with callbacks so this post is to fill that gap! If you didn’t read the previous post, the tl;dr is that Prism is a nodejs open source tool that can take your OpenAPI specification and then do an impression of your live API, validating the API calls sent to it and responding with the example data described in the spec. It can also follow up the API response and send an HTTP request of its own to mock the callbacks described in your OpenAPI spec. Continue reading →
16 Feb
2020

Make Thumbnails of PDF Pages with ImageMagick

All my talk slides are PDF – I use rst2pdf to transform text-based ReStructuredText content into presentation slides. With all these PDFs hanging around, it can be very handy to have them as thumbnails. I use the images both in the printable speaker notes that I produce (and I should blog that too now I’ve mentioned it), and to share on twitter – especially the resources slide that everyone photographs! My image file is much more readable than your cameraphone picture in terrible lighting :) So here’s my script for thumbnails in case you want to do the same; most presentation tools will export to PDF if you’re not already working in that format. Continue reading →
23 Jan
2020

Instant Test API Platforms with Prism

I’ve been writing a bit about OpenAPI lately and I realised that I didn’t share how I’m creating local, test versions of production APIs to work with while I develop new client code or test SDK features. The recipe is simple: you will need an API spec, the excellent open source tool Prism and an HTTP client. Mix it up and be ready to change your API development workflows forever. Continue reading →
15 Jan
2020

Grab Annotations from a PDF with pypdf2

If you’ve noticed a lot of PDF content around here lately, that’s because I work with PDF a lot! Most of all, all my slide decks are in PDF and in the last year or so I’ve started using speaker notes in my presentations. Yes, this means that if you saw me speak in the first ten years of my speaking career, that was without speaker notes.

There are some situations where I don’t have access to my speaker notes. Usually this is a good reason, such as I have mirrored my displays so I can demo or play a video without fiddling with my display settings in the middle of a talk. Sometimes, it’s because something bad happened and I’m presenting from someone else’s machine or a laptop that’s completely off stage and I only have the comfort monitor. For those situations I use a printed set of backup speaker notes so I thought I’d share the script that creates these.

Continue reading →