No REST for the wicked

Howtos, Tricks and Tips to build REST Servers

Gavin Mogan

Code Monkey @ Sauce Labs

@halkeye

https://www.gavinmogan.com

profile photo of gavin with hair in a mess

Whats going on?

  • Demonstration
  • How HTTP Works (basics)
  • Examples
  • "Best" Practices

Live Demo time

I need a volunteer

How does it work?

HTTP is made up of headers and bodies. Both on the request and the response side of things.

Request

Response

Live Demo time

Okay, backup time

              
                telnet localhost 8000
              
            
              
                GET / HTTP/1.0

Okay, backup time

              
                telnet google.com 80
              
            
              
                GET / HTTP/1.0

Types of HTTP Requests (1.0 - Simplified)

  • Getting Data
  • Should not change state
  • Should be repeatable
  • Just returns header, no body
  • Not really going to cover
  • Sending Data
  • Modifies state
  • No guarantees if sending again will do the same thing

HTTP/1.1 Added More

  • OPTIONS
  • PUT
  • DELETE
  • TRACE
  • CONNECT
  • Idempotent
  • "Save"
  • "Store at this location"
  • Idempotent
  • Delete this item (if exists)

Okay, how do I do it?

  • Sinatra (ruby)
  • Flask (python)
  • Express/Connect (node)
  • PHP
  • Rails (ruby)
  • Django (python)
  • Express + Sequalize (node)
  • Kohana (php)
  • Sympony (php)

Bare Bones

Sinatra (ruby)
Express (node)
Flask (python)
PHP 
              
                <?php echo "Hello World";

Rails (ruby)

"Best" Practices

URL Schemas

  • GET /resource - should return all
  • GET /resource/id - should return one

  • POST /resource - should add one

  • PUT/POST /resource/id - should update/store one

  • DELETE /resource/id - should delete one

Response Code

  • 200 - All good
  • 201 - Created Successfully
  • 301 - Always look here instead
  • 302 - Look here instead
  • 401 - Security pls. Who are you?
  • 402 - Not allowed
  • 404 - Not found
  • 418 - I'm a little tea pot
  • 500 - PANIC ERROR HAS HAPPENED

https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

JSON
vs
XML
vs
YAML

Tooling

Browser Tools

Documentation

  • Github self documents all their urls
    • See https://api.github.com/repos/appium/appium
  • Swagger, Blueprint, Probably more
  • Lots of companies roll their own.
  • Documentation is hard
  • Provide Examples
    • Snippets
    • Downloadable examples