Thank you to those who came to my talk today about CosmosDb. I hope you found it useful.
If you’d like to review the slides, you’ll find the presentation online here :
If you have any further questions please ask below and I’ll do my best to answer.
Tag: talks
Categories
The first rule of dog training
(EDIT : whilst the below line is an old joke, part of putting information out in public is making sure your facts are correct. So, for the dog trainers out there, as Christiaan Baes 🇧🇪 @chrissie1 points out, the first rule is Be Consistent, which means I can’t break this URL, but I will leave this note in place.)
The first rule of dog training is : know more than the dog.
If you pass that level, you’re ready to give a talk. Have you used node.js on a real project, or evaluated it properly against another framework? Have you failed badly on a project that would serve as a warning to others? Did you learn something important from your mentor or boss that they’re happy for you to share? What do you know now that you wish someone had told you last year?
When I first gave a talk in public, I was very nervous. I still get that way.
My first talk wasn’t an original idea. At the first DDD Scotland, I saw Ben Hall talking about Red, Green, Refactor and took the ideas away to try it properly, without fully understanding it (sorry, Ben). The following year, at the next DDD Scotland, I did a live coding session entitled “TDD? I don’t have time” that revisited the highlights of that talk, then filled in some of the lessons I learned from applying it. There was a bigger audience, and lots of fresh faces who found the idea interesting, but I didn’t plan it enough and it was very rough.
I started giving talks as a way to improve my communication skills. And on my first attempt, I failed badly. And I had to make the choice. Do I write it off, and retreat, or do I keep doing it so I can learn to do it better? It was a talk about agile principles, so I had to take the latter route.
So I did some user group talks, 20 minutes, instead of an hour. Some pikka machu talks, 6 minutes. I’ve since done workshops and guided conversations, where I let other people talk. I’ve paired with others to talk. I’ve talked about technology, people, other talks I’ve seen and the near future. I learned some tricks along the way, but Scott Hanselman (check out the related links too) and Christos Matskas summarise them much better than I could.
There are good reasons to speak at user group events, or conferences, or in your office. Don’t be afraid of being noticed. And if you want any more advice or encouragement, leave a comment or find me on Twitter or LinkedIn.
And don’t forget, DDD Scotland is back. Submit.
Categories
CodeCraftConf take-aways
I’ll let the other guides at CodeCraftConf summarise their talks if they wish, but here’s a few quick takeaways that I want to record.
Simplicity
Simplicity is always good to strive for, but the most interesting question for me is how to tell when code is not simple enough.
It happens when we get frustrated, and swear, when we start to experience cognitive drag when trying to understand what it does.
Cloud
Nothing is secure (just ask anyone who’s filled out the PCI compliance questionnaire)
Lean coffee
Alignment is the most important thing to get out of meetings.
2 backlogs – how do we capture the idea that not everything on the backlog is equal? Maybe you need a “ready to start” definition as well as a “definition of done. Maybe you need a “we’ll definitely complete this sprint” vs “we’ll look at these next”, or maybe you just need to read Warren Buffet talking about focus.
CitizenM is a big improvement over last year in terms of noise levels.
Many thanks to those of you who came along to my talk on why your API sucks. There were some great discussions during and after, and I hope I’ll be seeing slightly fewer reasons to tear my hair out in the near future.
A few things that people mentioned that I want to discuss again, as they’re not on the slides.
APIs still need a view model
There was a question about the API view of your data vs the database view. A good API still follows MVC principles. Just because a View is written in JSON instead of HTML doesn’t make it a model. Isolate it, because otherwise a database change is an API change. You can use automappers to save you having to write convertors, but always create a view for your API so you can handle versions and create consistency.
There was also a big discussion on how deep the hierarchy should be, particularly relating to data obesity. And it’s a different tradeoff if you’re optimising for poor latency, where larger packets with redundant informatio make more sense, or timeliness where small packets that can be built and parsed quickly are preferred. It all depends on your users. It may be the case, as the Trello API does, that returning the deep hierarchy is a request option so that the user can decide.
User Experience doesn’t always mean asking the user
Developers will ask for lots of things that aren’t useful. Sometimes you need to discover what the user needs are. Maybe it’s a test-first design. Maybe it’s a loosely typed API to help you discover what users want to do (think Google search vs Yahoo’s hierarchy – Google is more loosely types so was more likely to return odd results, but Google had lots of data on what people were searching for that it could learn from).
Link suggestions from the audience
Thanks for these suggestions. I’ll have to try them out myself, so I’m putting them here without warranty.
Kong – to consolidate your APIs, and create the polished surface that doesn’t expose the dirty, inconsistent history behind it.
RAML – to design a typed RESTful API up front so you know what it will look like.
Heroku’s HTTP API design guide
Slides from Google Docs
Slides from Slideshare
Categories
CodeCraftConf : call for guides
The CodeCraftConf call for guides is open, and I’d recommend either applying to be a guide or buying a ticket to attend. Last year’s CodeCraftConf was a great event, and I learned a lot.
For those of you unfamiliar with the guided conversations format, the conference website has a good write-up, but it’s a way to keep the conversation going by injecting new questions and riffing of old ones, to give everyone a chance to contribute.
If you want to be a good guide, be sure to share the conversation, and not let one or two individuals control it, especially if they’re in conflict.
If you want to apply, and you’re not sure what sort of questions to ask, have a look at my list from last year, and my write-up of the answers.
I hope to see you there.
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%208PLTomorrow:
HTTP POST http://www.example.com/api/getAddress X-www-form-urlencoded API-version: “v1.1” Search-type: “postcode-lookup” Input: “EH28 8PL”
Categories
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.
Categories
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.
Categories
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?
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.
Categories
Your API sucks : Domain languages
You have a massive data set. You have geolocation data for the entire country. You are the king of GIS. And to prove it, you’ve developed a postcode lookup so people can check your database.
Your clients write their code and format their postcodes, and, like every other system they use, they expect that submitting a postcode will return an address. You’re the GIS expert, and you say the result should return Easting and Northing, because that’s what your database uses, and your database is right.
The clients look at the result, realise that your API returns garbage because it’s not using the language they expect, and move on to another provider.
Congratulations, less users to support.
Craig Nicol 