Using steve - restapi

“steve comes with its own REST client API.”

“Seriously? There are dozens out there? Why roll your own?”

“Because the one I was using had issues and wasn’t being updated. I decided it was easier to just roll my own for my limited needs. Plus it was kind of fun to write.”

“Dude. steve is turning into a Frankenstein monster monstrosity. You need to see the doctor to cure you of your NIH syndrome.”

“Shh... I’m busy.”

Using the REST client API by itself

It’s similar to slumber except a little less feature(bug)-full. The gist of it is this:

  1. Import some stuff:

    from steve.restapi import API, RestAPIException, get_content
    
  2. Build an API object:

    api = API('http://localhost/v1/api/')
    
  3. Use the API object to fiddle with resources:

    # Get all Foos
    all_foos = api.foo.get()
    
    # Get foo with id 1
    foo_1 = get_content(api.foo(1).get())
    
    # Change the data, then put it
    foo_1['somekey'] = 'newvalue'
    api.foo(1).put(data=foo_1)
    
    # Create a new foo. This does a POST and if there's
    # a 201, it'll return the results of that.
    newfoo = get_content(api.foo.post(data={'somekey': 'newvalue'}))
    

That’s pretty much it!

Why get_content? That way you’re guaranteed that you have the requests Response object so you can see what’s going on. That makes this REST client API a bit easier to debug—it’s just a thin layer on top of requests.

steve.restapi

This is a REST client API since steve does a bunch of REST things with richard’s API. It’s a slim layer on top of requests.

steve.restapi.get_content(resp)

Returns the JSON content from a response.

Note

Mostly this just deals with the fact that requests changed .json from a property to a method. Once that settles out and we can use requests >= 1.0, then we can ditch this.

class steve.restapi.API(base_url)

Convenience wrapper around requests.

Example:

from steve.restapi import API

# Creates an api endpoint
api = API('http://pyvideo.org/v1/api/')

# Does a get for all videos
all_videos = api.video.get()

# Does a get for video with a specific id
video_1 = api.video(1).get()

# Update the data and then put it
video_1['somekey'] = 'newvalue'
api.video(1).put(data=video_1)

# Create a new video. This does a POST and if there's a
# redirect, will pick that up.
newvideo = api.video.post(data={'somekey': 'newvalue'})
class steve.restapi.Resource(**kwargs)

Convenience wrapper for requests.request.

HTTP methods return requests Response objects or throw exceptions in cases where things are weird.

class steve.restapi.RestAPIException(*args, **kwargs)
class steve.restapi.Http4xxException(*args, **kwargs)

Exception for 4xx errors.

These usually mean you did something wrong.

Property response:
 The full requests Response object.

Example:

from steve.restapi import Http4xxException

try:
    # do something here
except Http4xxException as exc:
    # oh noes! i did something wrogn!

    # This tells you the actual HTTP status code
    print exc.response.status_code

    # This tells you the content of the response---sometimes
    # the server will tell you an error message and it's
    # probably in here.
    print exc.response.content
class steve.restapi.Http5xxException(*args, **kwargs)

Exception for 5xx errors.

These usually mean the server did something wrong. Let me know.

Property response:
 The full requests Response object.

Example:

from steve.restapi import Http5xxException

try:
    # do something here
except Http5xxException as exc:
    # oh noes! i hit dumb willkg code and server is br0ken!

    # This tells you the actual HTTP status code
    print exc.response.status_code

    # This tells you the content of the response---sometimes
    # the server will tell you an error message and it's
    # probably in here.
    print exc.response.content