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
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
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>
The call to
c.service("zicpodes") will select the top level collection named
Step 3: Use filters¶
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')
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() >>> 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 u'22202' >>> print zipcode_resource.class_ u'Zipcode'
For example when representing a document in json, properties which are prefixed with $ are considered metadata.