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: presentations
Categories
Live coding during a presentation
I’ve done a few talks in my time, and some of them have involved live coding to help take the audience on a journey to understand the lesson I want to teach. It’s a technique I use rarely however as it can easily get problematic.
Live coding for a presentation is not the same thing as coding for your job or a mob session. Live coding for a presentation has to be as slick and as polished as the rest of the talk. No googling the API docs, no stumbling over syntax errors (although don’t worry if you don’t spot them, someone will.)
If you’re nervous with slides, live coding can help relieve some of the pressure. It certainly helped me when I was starting out, as I could pretend I was having a conversation with my computer for some of the talk. Fortunately, it was a conference with microphones.
Live coding is also great for presenting something novel (or at least novel for most of the audience) as it gets to demonstrate that it’s real and it works. I used it, in one presentation, to demonstrate TDD.
Be careful though. Technology can let you down, so have a think about how you might demonstrate another way. Do you have a video you can show on someone else’s laptop? Can you demonstrate with screenshots? Could you whiteboard a solution?
If you don’t feel comfortable writing code in front of an audience, don’t. Can the code (I use VS code snippets, but there’s plenty of macro choices), so you can reveal it gradually. Or pre-build it and uncomment as you go.
If you are preparing code in advance, to distribute with the slides, heavily comment the code so that when people download it afterwards they understand the context.
I do love to see live coding done well in a presentation, but unless you’ve prepared it meticulously, it won’t go well. Think about the story, and how and when you’re introducing new concepts. Don’t be afraid to go back to something later (“Here’s how to connect, but I want to show you search first. I’ll come back to the parameters here once you’ve seen the search results.”) It’s OK to refer to your notes, especially if you’ve just thrown up a screenful of code for the audience to read. Make every interaction useful.
It’s OK to backtrack. Show the mistakes you made, the error messages you saw, and how you corrected them. You won’t be the last person to make that mistake.
Relax and enjoy it. If code is what you do, be comfortable with it, even if the nerves are trying to turn you inside out from your stomach.
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.
Categories
Your API sucks : DDDScot follow-up
I was disappointed to miss DDD Scotland this this year, as I was looking forward to catching up with everyone and giving my talk. I’ll have to do the catching up another time, but if anyone wants me to give the talk, I’m available for conferences, user groups, weddings christenings…
There’s still a few discussion points I want to have around the talk, so I’m going to be posting some themes from the talk over the next few weeks to see what you think.
I wrote the talk as a catharsis for a project with 3 very bad APIs. I don’t want to name them in the talk because none of them were the first time I’d seen the problem, and I’m trying to list general anti-patterns so that other developers can avoid the pitfalls. The key one being that for all the user experience research, most people still think of users and interfaces as graphical, not programmatic.
Before I start the rants though, I want to start with 2 thoughts about making an api that sucks less.
Test-first
The best way to think of the user first, is to be the user first. That’s why I like Test-Driven Design. Write the API you want to use, then figure out all the horrible contortions behind the scenes to make it happen. That way you’re far less likely to introduce unexpected preconditions, because they’re harder to test. You’re far less likely to expose internal domain terms and models so long as you’re not thinking about them yet. And you get to experience any frustrations first hand when you’re best placed to fix them.
Use BDD, use xUnit, use Postman, use the wonderful new .Net core
TestServer.GetClient()
. Keep using them. Don’t accept any pain in your interface tests.
Rest, and be thankful
The talk unashamedly focuses on Web technology, and REST, for all the trial warfare, is a great way to think about the interface, and some of the basic lessons apply to other interfaces too:
- Be open for extension – where you can, build extension points into the interface. Use dynamic models if you can, allow discoverable interaction (I’ve got my order, what can I _do_ with it?)
- Use the standard – if you’re building on top of http, use headers, content-type, appropriate verbs, because existing clients and test frameworks support them, developers have learned how they work from other interfaces. Don’t be the stone in their shoe.
- Minimise state transfer – don’t ask clients to remember, don’t ask clients to send or receive large amounts of data. Scope requests to the smallest sensible unit, and only ask for what you need.
Anti-patterns
Sometimes it will go wrong, and you will make developers cry. I’ll start talking about those next time but feel free to add your own below.
I had the opportunity at work to revisit my Generic Algorithm talk, to refactor it with a bit more time to hopefully make it clearer. I also ported the C++ template code to Python to make it easier to demo. I’ll be talking about the implementation differences in a future post but I’ve included the links for the talk below for public consumption.
Craig Nicol 