Your Friendly Neighborhood – HTTP Status Codes – What's a status code?

View Github Repository Open presentation in a new window

minnesota-apis

See all presentation from minnesota-apis

Your Friendly Neighborhood – HTTP Status Codes – What's a status code?

0 0

october-2015-friendly-neighborhood-status-codes

October presentation, shown to the Minnesota APIs Meetup, talking through the standard HTTP status codes that everyone should know

On Github minnesota-apis / october-2015-friendly-neighborhood-status-codes

Your Friendly Neighborhood

HTTP Status Codes

Presented by Eric Caron / Made with Reveal.JS

What's a status code?

As defined in the 1996 IETF RFC-1945:

The Status-Code element is a 3-digit integer result code of the attempt to understand and satisfy the request. The Reason-Phrase is intended to give a short textual description of the Status-Code. The Status-Code is intended for use by automata and the Reason-Phrase is intended for the human user. The client is not required to examine or display the Reason-Phrase.

Wow. That was unpleasant.

Honestly, the 2014 HTTP/1.1 revision (RFC-7231) is a lot less painful.

The official list is maintained at http://www.iana.org/assignments/http-status-codes

We'll cover them from scratch anyway.

Because reading the RFC is only slightly more fun than putting on socks.

Let's play pretend!

You:

  • Have created an artificial intelligence application
  • Are not worried about it becoming SkyNet
  • Want to make people talk to it as a RESTful API
  • Plan to follow best practices for talking to it
  • Named it SmartBot7000, because the domain name was available.

FIRST RULE OF FIGHT CLUB HTTP STATUS CODES

If you ever make up your own code,

Where does that status code come into play?

Time for a live demo! We'll be using:

Run curl -v http://httpbin.org/status/418 in a terminal.

And that's how the web works.

Now we'll dive into the codes themselves.

High-level status code overview

  • 1xx - "Informational" (you'll never use this)
  • 2xx - "Successful" (you'll frequently use this)
  • 3xx - "Redirection" (you'll sometimes use this)
  • 4xx - "Client Error" (you'll frequently use this)
  • 5xx - "Server Error" (no comment)

Sidenote: I'm going to try focusing on the ones related to API communications. Twitter and Twilio serve as the basis for ones that are useful (though I'll expand if everything perks my interest.)

1xx Informational

Crickets chirp.

Unless you're making your own Chrome-competitor from scratch, you'll never need any of these.

2xx Successful

Code Meaning 200 OKEverything worked and you should feel happiness. Data is returned. 201 CREATEDSame as 200, except acknowledgement that you created something new. Data is returned. 204 NO CONTENTYour request worked fine, and there's nothing else to be said.

200 OK

Represents 99% of all successful conversations on the internet. Expected response for GET. Permissable response for all other verbs, though that's subject to debate.

Scenario

"Hey SmartBot7000, tell me your name."

HTTP/1.0 200 OK
Content-Type: text/plain; charset=utf-8

SmartBot7000. You could've come up with something better.

201 CREATED

Really should only be used when doing a POST and you're creating a document - this gives confirmation that it has been created.

Scenario

"Hey SmartBot7000, the capital of Iowa is Capital City."

HTTP/1.0 201 CREATED
Content-Type: text/plain; charset=utf-8

Good to know! I now know the capital of Iowa is Capital City.

204 NO CONTENT

Best for situations where you're deleting something and don't expect a change. When this happens in a web browser, they're not supposed to change the existing view.

Scenario

"Hey SmartBot7000, I was wrong about the capital of Iowa - delete it from your memory."

HTTP/1.0 204 NO CONTENT

Note: Use this one sparingly. People like to get data back, and it makes them sad when they don't.

3xx Redirection

Code Meaning 301 MOVED PERMANENTLYThe endpoint that you're looking for is forever going to live at this new location. 302 FOUNDThe endpoint that you're looking for is temporarily going to live at this new location. 304 NOT MODIFIEDThere was no new data to return.

301 & 302 Redirects…

This is great for browsers, but pretty confusing for APIs. If you have a properly versioned API, you should never be killing an endpoint. Stay away from this one in your API. *Cue Eric's confession*

304 NOT MODIFIED

Ideal for times when the client has some cached content, and the server says that cache is fresh enough. Beyond query string parameters, ETag and if-modified-since headers can also trigger this response.

Scenario

"Yo SmartBot7000. What's the most recent tweet by @ecaron in the last two hours?"

HTTP/1.0 304 NOT MODIFIED

4xx Client Error

Code Meaning 400 BAD REQUESTYou tried something and the server didn't like it. 401 UNAUTHORIZEDAccess is denied, but you're not logged in so that might be why. 402 PAYMENT REQUIREDIf your service requires $, you might want to send this. 403 FORBIDDENDenied. Go away. 404 NOT FOUNDDon't know what you were asking for, it isn't here anyway.

4xx Client Error continued

Code Meaning 405 METHOD NOT ALLOWEDYou're trying a GET, but the endpoint only supports a POST. 410 GONEShould not happen in an API. Like a 404, except it acknowledges it used to exist. 415 UNSUPPORTED MEDIA TYPEYou tried to upload XML, but the server only recognizes JSON. 418 I'M A TEAPOTAn example that April Fools' jokes are both awesome and awful. 420 ENHANCE YOUR CALMPopularized by Twitter, tells the client to slow down.

4xx Client Error continued

Code Meaning 426 UPGRADE REQUIREDThe server doesn't want to talk to the client in the dialect the client chose. 429 TOO MANY REQUESTSUsed for throttling.

That is a lot of Client Errors

Yes it is. 32 recognized errors, of which I think 10 are useful.

Which ones have people used?

400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 420 422 423 424 426 428 429 431 444 449 450 451 499

5xx Server Error

Code Meaning 500 INTERNAL SERVER ERRORYou didn't plan for this to happen, did you? 501 NOT IMPLEMENTEDYou're trying a verb called BLARKE? I don't know what that is. 503 SERVICE UNAVAILABLEServer is either overloaded or down for maintenance. 504 GATEWAY TIMEOUTThe server can't talk to the place it looks for answers.

5xx Server Error continued

Code Meaning 505 HTTP VERSION NOT SUPPORTEDClient might be trying 2.0, but server only handles 1.1. 508 LOOP DETECTEDSomething caused an infinite loop to happen. 509 BANDWIDTH LIMIT EXCEEDEDRemember getting Slashdotted? Good times…

5xx Server Error continued

The line between the Client and the Server causing the error is blurred. And confusing. Here's my rule of thumb:

  • If the client could have done something different to avoid an error, send a 4xx
  • Otherwise, send a 5xx

One More Note About 400 and 500

Although everyone loves getting a 200, 400 and 500 are generic and hard to compensate for. Although the attached "Response Status Message" provides insight, it isn't intended to be a programmatic-decision maker. These codes tend to become a catch-all and make long-term support difficult.

Whenever you are reviewing code and see a 400 or 500, double check to see if there's something better.There probably is.

Resources

I could make up more, but that is really all you need. And they're both made by Runscope, and although this wasn't intentional it felt worthy of being acknowledged.

If you're a visual learner, though, you might want to check out http://httpstatusdogs.com/ or https://http.cat/. They give visual reminders - either in canine or feline flavors - of what the primary codes mean.

Your Friendly Neighborhood HTTP Status Codes Presented by Eric Caron / Made with Reveal.JS