Documenting lists with Swagger

Swagger is a great tool for documenting APIs.  Not only it helps with keeping the documentation complete and up-to-date, but it also provides a handy sandbox for developers to play around with the API directly from the documentation.

We use Swagger a lot at work.  We’ve even pushed the bar slightly, but automatically generating the API documentation on the fly, to match the rest of our Qobrix functionality.  Whenever you change the database schema or the configuration of the fields, the changes are also reflected immediately in the API documentation.  And it works great!

One of the things that we haven’t done though until very recently is the documentation of the list fields.  Swagger provides the enum to document the values that can go into the field, but it’s not very helpful, when the values are not obvious.  Country codes and currency symbols work well, as they are common knowledge.  But if you have something custom, there needs to be a set of labels associated with the set of values.

The other day we decided that something is better than nothing, and added the documentation of the values as part of the field description (the property is described on the same page as enum above).  Here’s the Pull Request with the tiniest of changes.  And here’s how it looks in Swagger:

I admit, it’s not the prettiest of things, but at least the hints for the developers are there.  Also, since the list of labels uses a specific format, it’s quite easy to parse it out of the Swagger JSON automatically and reuse in third-party applications and services (like a website, connected to the system via the API).

While browsing around, I’ve also noticed that Swagger is growing and expanding. There is a new version of the specification – version 3.0, which has also been re-branded as OpenAPI Specification (see OpenAPI Initiative).  Here’s a great blog post that describes the differences between this and the previous versions, and here’s the migration guide for those who need it.

If you are working with PHP, zircote/swagger-php is the way to go.  It already even support the version 3.0.  If you are using the CakePHP framework, alt3/cakephp-swagger is the plugin for you (version 3.0 is not yet supported, but I’m sure it’ll get there soon).

Bitmask Constant Arguments in PHP

Liam Hammett (check many of his other excellent posts) has a nice explanation of the bitmask constant arguments in PHP.  These are fairly common and most PHP developers have seen them.  However, it’s been a few occasions where I discovered that especially newer developers don’t understand how this works.

Bitmask arguments and operations were used extensively in programming by the older generations, especially where CPU and memory were critical.  But with hardware getting so much cheaper over the last few decades, nobody really cares about an extra few memory bytes and CPU cycles.

Regardless of the memory and CPU though, bitmask arguments are still quite handy and using them can significantly simplify the code.

PHP Safe and Rector

I came across a couple of very interesting PHP libraries today.

The first one is thecodingmachine/safe.  This library wraps all PHP functions that return false on failure into another function that throws the exception instead. Think of all those file_get_contents() and json_decode() situations you had to code around.  Not anymore.  You can easily have them throw exceptions now.  Read this blog post for more details.

The second one is rectorphp/rector.  It is in fact mentioned in the documentation for the above library.  Rector is a refactoring (reconstruction and upgrade) tool that can easily change large chunks of your code.  Think of function renaming, parameter changes, and such.  Read these blog posts for more details: part 1, part 2, and part 3.

Very handy!

PHP assertions and assertion libraries

I’ve blogged about PHP assertions and assertion libraries a while back.  I haven’t started using the assertions anywhere outside of unit tests yet, but with more and more bloat added to the code to check for types and particular values, I keep coming back to the idea.

Today I came across a nice article by Matthias Noback which once again made me consider assertion libraries in my codebase.  I’ll discuss with colleagues and hopefully we’ll make the decision once and for all on whether assertions are a good way to go forward.

7 Tips to Write Exceptions Everyone Will Love

Tomas Votruba shares the “7 Tips to Write Exceptions Everyone Will Love“.  These all make a lot of sense and are generic enough to be applicable to any programming language (that implements exceptions).  The list of tips is as follows:

  1. Make Exception Names for Humans
  2. Use Quotes Around Statements
  3. What Exactly is Wrong?
  4. What is The Wrong Value?
  5. What File Exactly is Broken?
  6. What Options do I have?
  7. Link what You can’t Fit 140 Chars

Read the full article for both good and bad examples, as well as the explanations of the above.

The Alternative Dictionary of Web Design Terms

Webdesigner Depot runs “The Alternative Dictionary of Web Design Terms“.  It’s simple, yet pretty funny and accurate.  I liked all of it, but a few of my favorites are:

  • Agile: A development methodology that advocates self-organizing teams and flexibility, allowing startups to more efficiently realize they’re building something that no one wants.
  • Backlink: Before experimenting with dogs, Pavlov trained online marketers to salivate whenever he said “backlink”. It still works.
  • Code: The stuff they show on computer screens in the less-offensive Hollywood representations of hacking.
  • Comments (in Code): In-jokes and clever insights that only total nerds will ever see. One day, someone will achieve true enlightenment, and the secret will written down as a code comment, and lost to an obscure GitHub repository.
  • Navigation: The quickest and easiest way for a customer to get lost.
  • URL: U R Lost.


Cold War on Ice

Cold War on Ice is an excellent documentary about the USSR vs. Canada ice hockey Summit Series 1972 games.  I find it to be quite balanced, showing the perception from both sides, featuring the interviews with the same people back in the day and their take on it now, and plenty of great footage.

It’s a must see for any ice hockey fan and history nerd.

HipChat to Slack migration

Back in July, Slack acquired Hipchat with the intent of migrating all the users and shutting down the service.  For us at work, these were very sad news.  We’ve been using HipChat for years, and relied on it heavily.  We have also evaluated Slack in its early days and didn’t quite like it at the time.

Once it was clear that the HipChat is going away, we had a couple of options to consider.  One was to move to Slack.  Another – to migrate to a different solution, preferably to a self-hosted one, like Rocket.Chat.

So, first thing we did, was another test trial of Slack.  We were glad to see that it matured and improved a lot over the last few years, and that it would be faster and easier for us to move to Slack rather than to roll out our own self-hosted solution.

Here are a few things that we had to keep in mind for this migration:

  • We have a rather small team – about 15-20 people altogether, but with a very mixed backgrounds.  Some are very technical, some are not.  Some are on Windows, some on Linux, and some on MacOS.  Mobile use is also heavy across the board.
  • We are working with a lot of rooms/channels.  We have a few generic ones, like Support, Sales, Management, etc.  And we have a separate channel for every project.  And those we have over a hundred of.
  • We have a number of integrations connected – GitHub and BitBucket repositories, Zabbix monitoring system, RSS feeds, deployment automation, etc.
  • HipChat would only be around for the next month.  Not a tight deadline by our means, but the timeline is important here.

Since the time was limited from the beginning, we decided to start with the migration pretty much immediately, rather than waiting until the last moment.  In case something wasn’t working, we’d have some space to maneuver.

Instead of a once off switch, we also decided to do a gradual migration, shifting from HipChat to Slack bit by bit, using both services in parallel.

Creating the new workspace and registering all the users was, as you can imagine, the easiest part.  After all we do have only a small team, and that many accounts can be done manually, without any automation what so ever.

That was an option for the rooms/channels though, as we have hundreds of those.  Gladly, both Slack and HipChat provide an API which helps with automation, and we have awesome DevOps who handle things like that.

Here comes the first issue that we came across.  HipChat allows for much more when it comes to room names, than Slack.  Slack channels are limited to 21 characters (which is not a lot), and the selection of the characters is much less also (dashes are in, but slashes and other special characters are out).

That meant that we had to come up with the new naming convention, which we did.  We also used this opportunity to consolidate some of the HipChat rooms into fewer Slack channels.   In HipChat, as I mentioned, we had a separate room for each project.  Which was handy for busy projects, but somewhat confusing for smaller projects that belonged to the same client.  For example, it’s not a rare occurrence for us to have two, three or more projects for a single client.  And while they are all different, often they overlap a lot (websites for a group of company, or a website integrated with the CRM, etc).

Once we decided on the adjustments to the naming convention and consolidation of some rooms, the migration wasn’t too difficult, given the API of the both services.

Next came the integrations.  This is where, I have to say, Slack shines.  While HipChat integrates with both BitBucket and GitHub too, the functionality provided by Slack is a lot better and easier.  Both GitHub and BitBucket are available out of the box, so we quickly connected all the project channels to their appropriate repositories.

RSS feeds weren’t a problem either.  So the next one that we had to do was the Zabbix monitoring system.  Again, Zabbix is pretty good with integrating to other systems, Slack API is flexible, and our DevOps are amazing.  So that took no time at all. In fact, we even made it better, since Slack allows for richer and better notifications.

The last, but the most important one, was our deployment automation.  It wasn’t painful, but it did require us to do some adjustments.  Some of these we wanted to make for a while now anyway.  The biggest change was that HipChat didn’t care about the long running tasks, while Slack expects an answer from your webhook within 5 seconds.  Many of out deployments take longer than that (some are up to 20 minutes), so we had to do some changes.

When the chat webhook request for deployment is received, we couldn’t wait for the deployment to finish anymore to send the response back.  We had to respond within 5 seconds.  That meant that we had to disconnect the actual deployment run from the chat communications.  As I said, we wanted to do that for a while anyway.  A quick proof of concept with the Linux “at” command worked quite well, so stayed with that for the time being.  Now when the request is received, the deployment is scheduled with the “at” command for the next minute, and the response is sent to the chat within a second.

That was about it.  Since we didn’t care about migrating the actual chat histories or uploaded files or anything like that (we use Redmine for anything that needs persistence), the migration overall was smooth.

Once all the users were registered, channels created, and integrations configured, we started to phase out HipChat rooms one-by-one, archiving and disabling them on HipChat and pushing users more and more towards Slack.

Overall, the setup and configuration took us about three weeks.  The rest of the migration with the users and phasing out of HipChat took approximately another two weeks.

So, now that we’ve been using Slack exclusively for about a month and a half, how do we find it?  I think overall it’s a lot better now that it was with HipChat.  Here are some of the benefits:

  • The mobile app is amazing.  It supports multiple workspaces (some of our clients are also using Slack and we need to be in multiple places at the same time), has a great user interface, and, most importantly, the push notifications are working A LOT BETTER.  HipChat had a tendency of going offline after about 10 minutes and being completely silenced until the next manual check.  Slack even provides a Snooze option for 20 minutes, 1 hours, etc, which makes it easy to silence it during a meeting.
  • Slack desktop and web applications seem to be better enjoyed by non-technical users, than their HipChat alternatives were.  For me personally, HipChat was easier on the eye, but Slack provides a lot of functionality which wasn’t in HipChat.
  • Threads!  I think this is one of the greatest features that HipChat was missing.  Project rooms especially can get quite noisy.  It’s often difficult to follow up with all the chatter.  Threads make it a lot easier.  With threads there can be multiple concurrent conversations in the same channel without any confusion or overlap.
  • Reminders!  Again, for those of us who are busy with a million things, reminders in Slack are a killer feature.  They help to find that message that needs a response, half an our later, in a hundred rooms with dozens of conversations going on at the same time.
  • Slash commands.  While both HipChat and Slack have them, Slack allows to send the same slash command from any room (handy for deployments).  With HipChat we were a lot more limited, which pushed us into a separate room for all deployments.
  • Emojis.  Usually, I’m the last person to use emojis.  I’m the old school smiley guy.  But in this particular context, I find emojis to be very useful.  They often save a lot of typing and help keep the atmosphere nice and friendly.  HipChat had a very weird approach to emojis.  While they were there, they were very few, and very custom to the HipChat team.  We did upload a lot of our own over time, but with Slack that wasn’t necessary.
  • Stats and analytics.  Slack provides a great insight into how the workspace is being used.  Stats are available both as an admin menu item, and as a quick weekly email.
  • Integrations and API.  Slack provides a much more flexible API and integration options.  While we were doing fine with HipChat, I think all of our integrations are much better now because of the move to Slack.  (slash commands, updated messages, message replies, file attachments, rich messages, etc).

As I said, overall the migration went quite smooth and we are in a much better place now.  This is quite surprising and refreshing, especially after us considering the news of HipChat acquisition as a sad story.  In fact, I can’t remember, from the top of my head, when a sad story like this turned out to be such an improvement.

Thank you HipChat team for all the effort – you’ve been great for the last few years.  Thank you Slack for making things even better!