Getting started tutorial

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

Step 1: Configure the client

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


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

The URL where the Service document is located is named the API Entrypoint. In the provided example we used url as an entrypoint and selected the zipcodes service from the available services:

>>> from resty import client
>>> c = client.load("")
>>> c
<resty.types.Service object at 0x26abd10>

>>> zipcode_collection = c.service("zipcodes")
<resty.types.Collection object at 0x2597e90>


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

Step 3: Use filters

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')


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

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

At this point we have a zipcode_resource and we can extract informations like metadata and content specific informations

>>> print zipcode_resource.content.zipcode
>>> print zipcode_resource.class_


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