Categories
.net code data development

CosmosDb in The Real World : Azure Global Bootcamp 2019 (Glasgow)

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 :

CosmosDb In The Real World – GitPitch

If you have any further questions please ask below and I’ll do my best to answer.

Categories
code

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.

Categories
code development programming

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”
Categories
development

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
development

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
development

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.

Categories
development

Your API sucks : Domain languages

Developers are users too

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
development

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.

Categories
ai artificialintelligence c++ code development programming search

Updated slides on Genetic Algorithms

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.

Categories
code development programming security

CodeCraftConf by @codecraftuk

Follow @codecraftuk on twitter
CodeCraft logo

The tickets for CodeCraftConf are now on sale. It’s based around the idea of full participation, where every attendee is there to discuss the topics. The format is of guided conversations, which has worked well for sessions in the past, and I’ve included a list of some of my previous sessions using a similar format below for reference. I’ve used the mindmap format for sessions I’ve done in the past so that there is a solid summary that attendees can refer to if they wish, but I have also been involved in sessions at other conferences that were deliberately transient in order to foster honesty and controlled venting, more like a support group for frustrated developers.

I am looking to guide a session at the conference and will be talking to the organisers about the topics,. If you look at the list below, and the conditions on the conference site, it should be clear that this will be a philosophy of code conference rather than a discussion of all the hot technology you don’t know about yet, but really should. (and number 5 will change your life forever).

I realise that holding the conference in a pub, even one as good as Drygate, will challenge the training budgets of some companies, but it looks like a great concept, and I hope the conference takes off. Many thanks to Joe and Gary for bringing this together, and I look forward to meeting everyone there.

What you missed at DDDs

My previous chaired discussion sessions, with mindmaps for reference.