The importance of language: acknowledgements

There’s a few little things that sneak in to conversations and emails that you probably don’t realise you’re doing, until someone points them out to you.

No problem VS You’re welcome

Darlene Price has a great list of phrases you should never say at work. One that really stuck with me was replying to “thanks”, with “no problem”. It was something I did reflexively, either because I thought I was Australian, or because I wanted to minimise the work I’d done. As the article above explains however, it also implies that it would be a problem in other circumstances. Whilst that may be true, there’s an implicit “it’s OK, this time” vibe that, once I spotted it, started to come across to me like a passive aggressive threat. I don’t think that’s how it was perceived, but once I saw that, I couldn’t unsee it, so stopped using “no problem” almost immediately after reading that article.

You’re smart VS You worked hard

This is a parenting basic tip, but it’s a useful thought in general. If you’re smart, then you’re #1, so why try harder. If you worked hard, then you can see the effoer for your reward, and hard work is not a barrier to future success. If you’re smart and you fail, then you’re just not smart enough. If you worked hard and fail, then you either keep working, or seek help. It’s OK to ask for help if you’ve put effort in and need support. It’s not OK if you’re not smart enough, your ego will get in the way.

Advertisement

Your API sucks : foolish inconsistency

There are many ways that an API can be inconsistent. Different methods can follow different conventions, one method may have different results, or maybe a change introduces inconsistency between versions.

Spatial Inconsistency

When calling 2 different methods in what appear to be related domains require 2 very different calls and get 2 very different results.

GET /cat

{ Name : “Garfield” }

GET /food/index.php/fooditem/1

                    🍌

Random Inconsistency

When calling the same method multiple times can lead to a result with a significantly different format.

GET /cat

{ Name : “Garfield” }

GET /cat

{ Name : “Jatt” }

GET /cat

{ Name : “Lion-o” }

GET /cat

🍌

Temporal Inconsistency

When versioning an API breaks existing clients without warning. Speak to Seb Lambla if you want to do it without versioning, or Troy Hunt if you want to version it right, in all the wrong ways.

Today:

http://www.example.com/api/getAddress?postcode=EH28%208PL

Tomorrow:

HTTP POST
 http://www.example.com/api/getAddress
 X-www-form-urlencoded
  API-version: “v1.1”
  Search-type: “postcode-lookup”
  Input: “EH28 8PL”

Scottish Developers – Your API sucks: live

I’m pleased to announce that my talk “Developers Are Users Too : Why the User Experience of Your API Sucks”, postponed from DDD Scotland, will be held at RookieOven in Glasgow on Tuesday 16th August. Tickets are available on Eventbrite.

Many thanks to Scottiswh Developers for the invite and to RookieOven for hosting. I hope to see you all there.

The Talk

I’ve written clients for a lot of APIs, and most APIs suck.

People pay lip service to good design of web sites and applications, but where’s the UX designers for your API? I’m sure you’re sprinkling a little TDD on it, and you’re drinking the RESTful Kool-Aid.

You’re still doing it wrong.

Here’s some things to think about to make sure you’re not woken up in the middle of the night by an angry horde of developers hating you and your API.

The Speaker : Craig Nicol

I am a polyglot developer and a technical lead, normally found in ASP.Net and JavaScript but also Python and other, more esoteric languages. I am passionate about the Web, and open compatibility. I like to push technology in unusual ways to see what it’s capable of. I blog about code craft, Web development, software teams, Web security, and anything else that I think can be improved in the software world.

Register Now

Your API sucks : Error handling

Exceptional validation

So many places I’ve seen throw an exception for the first validation error they encounter:

HTTP 500 - Credit Card number invalid

When I see that, I need to make multiple calls before I can see what’s wrong. If you’re going to validate, try and validate everything beyond authentication in one shot, like this:

HTTP 400

{
    validationErrors: [
        {"CreditCardNumber" : "Must be 16 characters"}
        {"ExpiryDate" : "Must be in the future"}
        {"CCV" : "Is required"}
    ]
}

Success : ERROR

If something went wrong, make it obvious. On the web, use a 4xx or 5xx status code, instead of a 200 OK. In code, throw an exception. This isn’t C, we don’t need to rely on errno any more. If I see success, I want valid data. Parsing your error messages isn’t part of the deal. Especially if they have spelling mistakes.

Illegal characters

If I see that your API won’t let me have O’Malley as a name, or Flat 1/2 as an address, I will immediately start thinking of Bobby Tables, and I will assume you have a poor encoding excuse at your backend. If you can’t handle that, you shouldn’t be writing an API. As the security sucks said, you should not be my weakest link.

The importance of language: company culture

There’s language you use in a team that defines the project. The language that a company uses defines every project. Get it right and the company makes people happy. Get it wrong and your staff, and your customers, will start asking what’s wrong, and you might not be able to tell them.

Don’t be creative

Software development is just a matter of sitting in front of a keyboard and typing. Thinking isn’t software development. Designing isn’t software development. Talking isn’t software development. Even if it’s talking to a duck. Therefore, in order not to disturb those who are working, get away from your desk and go be creative somewhere else, you anti-social malcontent.

Or maybe lateral thinking and problem solving are exactly what you’re paying software developers to do. Just because you don’t understand the beauty of what’s being produced, doesn’t mean the beauty isn’t there. I understand developers need quiet time, but most developers (and any developer I’d want to work with) need to be social. Sometimes you talk through a problem, sometimes you debate alternatives, and sometimes you chat over a coffee to take your mind off the problem for long enough to be able to find the solution.

Just one little thing 

Software development is easy. Sure, there’s hard problems, but that’s what those other guys in Microsoft, and Google, and Apple do, not us. So those requirements we asked for an hour ago, should be done by now, right? After all, it was just one change to our database to support transgender employees.

OK, so I didn’t realise we didn’t have Mx as a title, but that’s just one other little change, right? No, I don’t know what a boolean is, or what that’s got to do with the gender column, but you can just add one more value, can’t you? I don’t know whether all the historical records need to be changed, I’m not a developer, can you just add support for transgender or not?

Just is a very dangerous word.

Right first time

We’re a company that our users can trust. We don’t make mistakes. We do it right, first time, every time. And anyone who doesn’t can go work for someone else. Losers.

Or, we’re a company that doesn’t take risks. We’re scared to fail and we don’t know how to recover from failures. If we make one mistake, our house of cards will fall and our users will leave. We don’t innovate, we can’t adapt. And if we fail, we’ll blame someone else. We’ll brag about our self importance to cover up our tiny exposure, and we’ll come down like a ton of bricks on anyone who questions us.

Don’t be that company. Sometimes things fail. Expect failures, expect things to go wrong. Figure out how to recover. A customer who has a complaint dealt with quickly is often a happier customer, and a better ambassador, than a customer who hasn’t, or can’t complain. Don’t make mistakes for the sake of it, but take risks, be interesting, and learn to right yourself when you capsize.

Your API sucks : hidden effects

Your API can be well structured and use the right language on the surface, but it can still be a pig if you get it wrong behind the scenes.

Data bloat

Are you sending 1/2 Gb of data for every roundtrip? XML encoding the entire object graph for a call that can only possibly change 1 field within it? Are you wondering why your network is slow?

Busy waiting

Sometimes data is big. It will take a long time to upload and process. That doesn’t have to be a problem. But don’t make me wait whilst you do it. It’s easy to find asynchronous libraries, or just throw the request in a queue and return. Let the client get on with the next thing.

Idempotence

Idempotence is a posh word for a very simple idea : looking at something shouldn’t change it. Quantum mechanics is hard because that’s not true. Your API is not there to impress Niels Bohr.

In other words, GET over HTTP doesn’t change data. Property getters on a class don’t change data. CQRS queries don’t change data. Don’t change data unless explicitly requested to do so.

Don’t get confused though. This doesn’t mean that each get will return the same result, after all tomorrow’s weather will be different to today, but I should be able to change the weather just by observing it.

Hidden prerequisites

Have you ever visited a shopping site and tried to checkout, only to be denied because you haven’t previously added a credit card to your account?

It’s very annoying having a hidden step that’s not clear. If it’s required, make it required at the point of action (definitely my preferred option), or if you can’t do that, deny access to the point of action until the prerequisites are cleared. And make it very clear why access is denied.

The importance of language: team culture

As a leader, whether within a technical team, or a technology expert leading a customer, the use of language is very important. It’s a soft skill that’s lacking in a lot of developers and non-developers. I try to be cautious about my use of language, partly because I’ve had mentors who treat imprecision or careless word choice as a bug, and partly because I’ve been in enough situations, as the speaker or the listener, where language has been the primary reason for conflict. I’ve also taken creative writing courses where ambiguity is expressly allowed, and brevity is actively celebrated. When your words are limited, you have to choose them carefully.

I’ve got a few posts coming up around this, with some links to interesting articles if you want to dig deeper into this, but I’m interested to hear your thoughts too.

Manager vs leader

A manager tells you what to do and monitors you to make sure you do it. A leader sets priorities and trusts you to get on with it, and clears the path to let you do it. A manager puts the team in a box and reflects it to the outside world. A leader puts the rest of the world in a box and reflects it to the team.

Not everyone with the title fits the mould, but there’s an attitude that the title gives you about your role in the team, and the expectations of what you should be doing.

Perfect vs perfect

Rackspace has a nice blog about perfect as a process rather than a destination. Quality is what we want as a team, but every release we do, every code we touch, can be refined, adapted to new practices as we learn where the weaknesses are. We hone our skills, and our code, removing weaknesses and rough edges, but we accept there is always more to do.

Nothing is ever going to be “as good as we can make it”, but it can be “good enough”. Software that hasn’t shipped is a project, not a product. Make products, ships them, get feedback. If you strive for perfection, feedback is an opportunity to improve, if you believe your product is perfect, feedback is dismissed as noise.

Your API sucks : security

Pop quiz time.

You are given the following example URL to GET as an example of making a payment from your application. How many things here would make you back away slowly before setting the server farm on fire?

http://www.example.com/api/pay?cardnumber=1234123412341234&ccv=1234&expirymonth=12&expiryyear=12&amountinpence=123456

So you complain it’s unsecured and they come back with an upgrade, so you need to make the following call first:

http://www.example.com/api/pay?username=bob&password=supersecret

If you’re sensible, you will walk away. A API should never be the weakest link in your code. Remember, you own everything, including the turtles all the way down. Users don’t care that it was Honest Joe’s Honest Payment Provider that had a security hole, it was your site that took their details, so it’s you they will blame.