The RESTful API has a funny place in the software development world: it’s widely regarded as the best general-purpose pattern for building web application APIs, and yet it’s also nebulous enough of a concept to cause endless disagreements within teams over exactly how to implement one.
Do I make my endpoint
/companies/123/? How about
/locations/?company=123 ? How do I handle versioning the API? Why shouldn’t I send a POST request to trigger an action on the server? If a backend task can take many seconds to process, how do I represent that in the API?
A couple of years ago, I developed an ‘operational support system’ for anaesthesiologists
working in the OR. Other than the main goal of enhancing Patient Safety by helping the
docs remember to do all the things they need to do before, during and after a surgery, the
requirements for the product were quite vague. This wasn’t particularly surprising to me
as this concept, though not new, had never been implemented as a computer system that could
be used in operating rooms and while certainly ‘technical’ to some degree, my customer was
not versed in software development and really didn’t have many expectations beyond the
implementation of his core concept. Anyway, with that comforting level of detail, I set out
to design a system that would both meet the main goal while at the same time being able to
accommodate the inevitable “oh yeah, we should be able to do, too – that won’t take
too long, will it?”.
One of our most frequent tasks as programmers is assigning names. It’s hard to go an hour without coming up with a name for a class, a method, or a variable. But naming things is hard for at least two reasons:
- The exact purpose of an item might be not be clear until you’ve written its body or used it in context. I often use a clearly inappropriate placeholder that will force me to replace it once I have a good name.
- Picking appropriate words is tough. It can be hard to spend time selecting the right word when you’re focused on writing logic, but often the work of naming will help clarify that logic’s organization.
Here are some suggestions for naming rules, born from recent experiences.
“I only modified one line of the file, why should I be responsible for fixing the coding style of the whole thing?” That was my first reaction when participating in a full-scale code review at one of the software companies I worked for. Then, if I do have to fix the coding style, my name is going to be on the blame list when somebody checks version control for who wrote that section of code. How far should we take fixing things during reviews? (more…)
When I started my own personal site, I faced a dilemma: I’m a software developer, why should I use a content management system (CMS) on my personal website when I’m supposed to be an expert at making websites? Every CMS I’ve used has angered me in one way or another. The end result was always me hacking together my personal site with PHP (the one thing the language was originally designed for) or playing around with other custom backend solutions for it.
A static website with a dynamic backend though seemed wasteful to me. Every time somebody visits the page, the web server must regenerate the content for the page. The engineer inside of my head was screaming “surely there’s a better way to do this!” (more…)