Browsed by
Category: General

HTTP status for API Responses

HTTP status for API Responses

In designing an API it’s a challenge to understand when to use HTTP error responses and HTTP OK (200) responses. As with many organizations it’s something that can be subject to lots of passionate debate. Let’s look at a bunch of different scenarios.

Let’s take an OAuth 2.0 API that looks something like this, with an assumed HTTP Authentication header.

Imaging responses look something like:

Where error is option if the ok boolean is False, otherwise there is a data payload appropriate to the API response.

 

data.search(query=”car”, count=15)

Return ok=true, code=200 and results=[array]

data.search(count=15)

Return ok=false, code=400, error=”query_not_found” – required parameter not present

data.search(query=”(car”, count=15) 

Return ok=false code=200 error=”query_syntax” – there is a syntax error in the query

data.search(query=”car”, count=”xyz”)

Return ok=false code=200 error=”malformed_count” – count isn’t a number

Shouldn’t errors be HTTP 400?

The discussion wouldn’t be so interesting if there was one answer to this. The objective is to differentiate between structural problems with your API requests and potentially customer generated syntax problem.

When you return a HTTP 400 level error you’re indicating a few key things:

  • Authentication errors
  • Rate limit errors
  • Non-existent endpoints
  • Missing mandatory parameters in requests

When you group syntax level events in here, it’s useful but what it means is when carried to an extreme you could have an autocomplete API endpoint that when there is no autocomplete results would return a HTTP 404 no results — that would be for a valid API query with valid parameters. When you’re doing an audit of your endpoints you cannot quickly determine if somebody is calling your API with missing parameters or it’s just normal events.

You could even argue in this model missing mandatory parameters are 200 – hold that thought.

Client Considerations

When a client dispatches a request what should it do with the error, let’s assume that you’re using a client that has request interceptors as part of the flow. Where if you were to call with a 401 Authentication error you would route the user to login in someway. This would be independent of the specific handler in your UI or application – similar if it’s server side the 429 rate limit would kick in and take an action above what your regular API was doing.

Now back to that syntax error, if you’re returning a 400 level event your interceptor logic is going to have to step in and try to understand why that problem happened and may or may not route back to the code that did the dispatch.

Now if you leave the 400 level HTTP errors to indicate that there was a problem with the call you can route all of these back to the code that dispatched and it can make local decisions for the right behavior is. It’s not an “error” for there to be no results to autocomplete, that’s normal expectations.

If you’re missing required parameters, you’ve got a serious bug in your code. That should be indicated in a way that’s distinct from normal failure.

Recommendation

Given the idea that you want to have errors be programatic errors and ok’s be valid, this is what should be used for HTTP response code for APIs.

HTTP Code Description
200 Structurally valid API request made – API “ok” boolean indicates details
400 No authentication provided or missing required parameter
401 Invalid authentication token
404 Endpoint doesn’t exist
429 Rate limited
500 Internal error – this should be returned even when a backend dies

 

 

 

FizzBuzz of the day

FizzBuzz of the day

Like many pieces of code, there is always a story behind it.

Your FizzBuzz solutions of the day – using operator precedence to get a result

Or on one line.

 

Skiing Tahoe

Skiing Tahoe

A friend asked me the other day about skiing in the Tahoe area. This was for him and his wife getting back into skiing after being out of it for a few years.

Note: I will update this page, but for now I thought this table was really useful.

Destination Resorts

These are all resorts that are higher priced and have lots of acreage to choose from. They will have more village options for apres ski and lodging options at the base of the mountain.

Name Base Elevation Vertical Drop Acres Ticket Price
Heavenly 6565ft 3502ft 4800 acres $140
Northstar At Tahoe 6330ft 2280ft 3000 acres $140
Squaw/Alpine 6200ft 2850ft 6000 acres $134

Classic – Midsized Resorts

Served by classic lodges and you’ll have to commute to and from them. They are smaller in size and typically have lower ticket prices than the Destination resorts.

Name Base Elevation Vertical Drop Acres Ticket Price
Homewood 6229ft 1650ft 1260 ac $74
Mount Rose 8260ft 1800ft 1200 ac $104
Sierra-At-Tahoe 6639ft 2212ft 2000 ac $93
Sugar Bowl 6883 ft 1500ft 1650 ac $103

Small

These are the small resorts in terms of acreage, many will still only have fixed grip chairs (slower) and less vertical feet to ski. The upside is that the ticket prices and lesson prices are lower which can make for great learning hills.

Name Base Elevation Vertical Drop Acres Ticket Price
Boreal 7200ft 500ft 380 ac $59
Diamond Peak 6700ft 1840ft 655 ac $64
Donner Ski Ranch 7031ft 1000ft 505 ac $59
Soda Springs 6700ft 652ft 200 ac $69
Tahoe Donner 6750ft 600ft 120 ac $47

 

Delivering Delight Requires Execution

Delivering Delight Requires Execution

I do like delight, I really do.

I was wondering last night about why saved searches have sucked for so long. Got thinking about some slides I’m putting together about quality. Part of it is that “move fast and break things” is counter productive to where we need to be, we need to move fast, but letting people internalize “break things” is part of why I think we’ve not put the attention into resolving it (aka excellence).
Maybe it’s —
   Deliver delight by excellent execution
If this was SGI, it probably would have been a BINGO (http://www.geometer.org/sgi/wsj.txt)
Though that’s the concept that I think is important. We can’t delight folks if we’re not striving for excellence. Excellence alone allows us to focus on the weeds and the not the result – think about polishing a rock, prettiest rock ever, still a rock.

 

ES6 and Angular + a little GoLang

ES6 and Angular + a little GoLang

This post really documents the checkpoint in my experiments with GoLang and Frontend development.  As some people might know that I’ve been playing around with application structure, languages and approaches for a while.

My GoLang AngularJS and ES6 Todo App over at GitHub – it’s the reference for the rest of this post.

File Layout

Some quick to points, general directory structure:

One general note is that I haven’t found an idiomatic directory structure for GoLang application development.  IMHO “app” should be the handlers and have a model/conf directory.  Still a work in progress.

While this is an ES6 experiment, I did look at TypeScript for a bit and while I like it due to being a typed language which should reduce a class of errors. I did have to wonder about is the cost of building the type definition files for projects worthwhile?  In a large organization I could see that this would pay dividends, but not clear from the get go.

What’s good about ES6

For past projects I’ve used CoffeeScript, since that is the standard which Tubular uses for projects and it’s always good to keep your mind working.  Plus as a Python/C programmer at heart I do find the CoffeeScript syntax where the parens are optional occasionally a bit hard to parse.

Top 3 likes of ES6

  1. classes
  2. import
  3. “=>” for functions

While it might be possible to go on, I haven’t had the chance to really fully exercise the language for my little ToDo app.  With the first two items the real need of CoffeeScript is diminished and allows you to program to the standard.

General App Structure

This is where preference starts showing up.  How to structure a good AngularJS application.  I’m sure there is some conventions that I’m not following, either through ignorance or rebelliousness.  The biggest area where I think application standards are interesting is routing.

What I think is important is the ability to say in your main.es6 file:

Then to have todo contain:

 This way you’re having the routing next to the controller, rather than having a massive route.es6 file which documents the whole application.

Note:  You’ll see that I also make use of browserify to load HTML into the controllers directly.  This makes it really easy to compress the whole application into a solid Single Page Application.

Conclusion

I think ES6 is a good framework for building out AngularJS applications. The general problem is application structure, which is always a combination of personal preferences and habits.  That said, the Grunt flow with Babel and ES6 is easy to setup and make the code much cleaner.

Continuous Integration Process

Continuous Integration Process

Was at a wonderful conference hosted by one of Tubular’s investors (FirstMark) where VPE’s, CTOs and key technical leads got together from a bunch of their investments to listen to speakers and have some good round table discussions.  I spent my time participating in a round table on development processes, which evolved quickly from “life is good” to “here is a rough spot we’re having’. It’s really refreshing to have honest communication about your problems rather than having to wear the customer facing hat of the world is perfect and of course we will meet your every need.  Note; Customers we do meet your ever need, sometimes the process is less than perfect to get there.

As we were wrapping up and went to grab buffet lunch. Was chatting about what we would do sooner now that we have a bit of perspective on what it takes to go from two people at a desk with an idea, to an organization.  What’s interesting is that we all agreed that putting Continuous Integration into the process earlier would be better, while this means different things to different people.  At the core —

  1. Setting up git auto builds with Travis CI – everybody thought that was the best place to start, with migration to Jenkins as inevitable
  2. Getting Unit Testing / Integration Testing in place
  3. Getting Continuous Deployment working

Having those three things early in an organization will help lay the fundamentals of a culture that will be more agile and able to iterate faster as the company grows.

Having the first two are bread-and-butter in the modern development practices, having Continuous Deployment is the big nut.  Why? It ensures that the responsibility for delivering quality code never leaves the engineering organization, that makes sure you stay agile.  The moment you introduce QA you will always have large releases, now you have a bottleneck on what goes out and lots of finger pointing at who is responsible.

Question: Who is responsible for code quality?
Answer: Engineering

As leadership in engineering my goal is to make sure that we understand that is our commitment.  So setting up tools early to make it easier to grow cannot be underestimated.