



resty 0.1.1 documentation

### Navigation

* [resty 0.1.1 documentation](index.html#document-index) »

Welcome to resty’s documentation![¶](#welcome-to-resty-s-documentation "Permalink to this headline")

====================================================================================================

`resty` library provides user-friendly abstractions that allow you to easily interact with RESTful API. This documentation contains guidance on how to install and use the library.

`resty` is:

* simple high-level API interaction

* easy to use

* smart

Contents:

Installation[¶](#installation "Permalink to this headline")

-----------------------------------------------------------

This tutorial will walk you through the process of installing resty

### Install `resty`[¶](#install-resty "Permalink to this headline")

The installation can be easy done by using the *easy\_install*:

```

easy_install resty

```

You can upgrade your older version too:

```

easy_install --upgrade resty

```

Or using *pip*:

```

pip install resty

```

Getting started tutorial[¶](#getting-started-tutorial "Permalink to this headline")

-----------------------------------------------------------------------------------

This tutorial aims to get you started with `resty` as quickly as possible.

It is made up of a number of examples of increasing complexity, each of which shows one or more useful `resty` features.

If you have any comments about these tutorials, or suggestions for things we should cover in them, then please contact us via [Github](https://github.com/pbs/resty/)

### Step 1: Configure the client[¶](#step-1-configure-the-client "Permalink to this headline")

`resty` provides two types of clients:

* the default `client` - uses summaries if available therefore the interactions with the api are optimized

* `dumb\_client` - does not use summaries and relies strictly on links

Note

The summary is composed from all additional attributes (not required) that a minimum document representation has. The minimum documentation representation is used whenever a document has a relationship to another document.

### Step 2: Load the entrypoint and select a service[¶](#step-2-load-the-entrypoint-and-select-a-service "Permalink to this headline")

The URL where the Service document is located is named the API Entrypoint.

In the provided example we used `http://services.pbs.org/` url as an entrypoint and selected the zipcodes service from the available services:

```

>>> from resty import client

>>> c = client.load("http://services.pbs.org/")

>>> c

<resty.types.Service object at 0x26abd10>

>>> zipcode\_collection = c.service("zipcodes")

<resty.types.Collection object at 0x2597e90>

```

Note

The call to `c.service("zicpodes")` will select the top level collection named `zipcodes`.

### Step 3: Use filters[¶](#step-3-use-filters "Permalink to this headline")

The `filters` are used to describe complex interactions that usually require some sort of human input. One particularly common situation is searching trough the elements of a collection. Templates are available only in collections. Since `zipcode\_collection` returns a collection we can filter it based on zip.

```

>>> filtered\_zipcodes = zipcode\_collection.filter('zip', zipcode='22202')

```

Note

The `filter` method takes one positional argument that represents the filter name and a number of keyword arguments where the keys represent the placeholder names and the desired values.

### Step 4: Iterating through items[¶](#step-4-iterating-through-items "Permalink to this headline")

Items represents the list of objects available in that collection. In the above example the `filtered\_zipcodes` returns a collection with a single object. Let’s select the first object from the list:

```

>>> zipcode\_resource = filtered\_zipcodes.items()[0]

>>> zipcode\_resource

<resty.types.Resource object at 0x259fc50>

```

### Step 5: Accessing metadata and usefull content[¶](#step-5-accessing-metadata-and-usefull-content "Permalink to this headline")

At this point we have a `zipcode\_resource` and we can extract informations like metadata and content specific informations

```

>>> print zipcode\_resource.content.zipcode

u'22202'

>>> print zipcode\_resource.class\_

u'Zipcode'

```

Note

For example when representing a document in json, properties which are prefixed with $ are considered metadata.

### Step 6: Using links to interact with available relationships[¶](#step-6-using-links-to-interact-with-available-relationships "Permalink to this headline")

Using the `related` method one can get from a document to a related document by specifying the relationship name.

Let’s see all the callsigns that are available for zipcode 22202 with their corresponding confidence:

```

>>> callsign\_collection = zipcode\_resource.related('search')

>>> for c in callsign\_collection.items():

>>>     print c.related('related').content.callsign, c.content.confidence

WETA 100

WMPB 100

WWPB 100

WHUT 100

WFPT 100

WVPY 100

WMPT 100

WGTV 80

KRMA 80

WTTW 80

WTVS 0

KCTS 0

KSPS 0

WGBH 0

WNED 0

```

Note

The `related` method takes one argument that represents the relationship name. In case there are multiple relationship with the same name one can pass an additional argument representing the related resource class or in case of a colletion the type of the elements.

In the above example the call to `c.related('related')` is equivalent to `c.related('related', 'Callsign')`

What’s new in resty 0.1?[¶](#what-s-new-in-resty-0-1 "Permalink to this headline")

----------------------------------------------------------------------------------

We are pleased to announce the initial release of the `resty` library.

As this is the first version of `resty` library, these are the main features.

### Features[¶](#features "Permalink to this headline")

* simple high-level API interaction

* easy to use

* smart

Indices and tables[¶](#indices-and-tables "Permalink to this headline")

=======================================================================

* [Index](genindex.html)

* [Module Index](py-modindex.html)

* [Search Page](search.html)

### [Table Of Contents](index.html#document-index)

* [Installation](index.html#document-installing)

	+ [Install `resty`](index.html#install-resty)

* [Getting started tutorial](index.html#document-tutorial)

	+ [Step 1: Configure the client](index.html#step-1-configure-the-client)

	+ [Step 2: Load the entrypoint and select a service](index.html#step-2-load-the-entrypoint-and-select-a-service)

	+ [Step 3: Use filters](index.html#step-3-use-filters)

	+ [Step 4: Iterating through items](index.html#step-4-iterating-through-items)

	+ [Step 5: Accessing metadata and usefull content](index.html#step-5-accessing-metadata-and-usefull-content)

	+ [Step 6: Using links to interact with available relationships](index.html#step-6-using-links-to-interact-with-available-relationships)

* [What’s new in resty 0.1?](index.html#document-releases)

	+ [Features](index.html#features)

### Quick search

 Enter search terms or a module, class or function name.

 

### Navigation

* [resty 0.1.1 documentation](index.html#document-index) »

 © Copyright 2012, Core Services Team.

 Created using [Sphinx](http://sphinx-doc.org/) 1.3.5.

 

