Wiki

Clone wiki

path_to / Home

PathTo

DESCRIPTION

Resource-oriented client APIs generated dynamically from auto-discovered or locally-configured metadata.

Support for the core metadata is provided in Python in DescribedRoutes.

CONTENTS

  • EXAMPLES
  • Initialization
  • Navigation
  • HTTP and JSON interfaces
  • AUTHOR AND CONTACT INFORMATION
  • APPENDIX - SAMPLE JSON

EXAMPLES

Initialization

Initialise from a server that supports auto-discovery via link headers:

>>> from path_to import open_app
>>> app = open_app('http://example.com/users/')

Initialise with the metadata shown in the appendix at the end of this file. Typically provided by the server in JSON or YAML.

>>> from path_to import Application
>>> app = Application(...)
>>> print app.resource_templates
users              users         GET, POST        http://example.com/users{.format}
  new              new_user      GET              http://example.com/users/new{.format}
  {user_id}        user          GET, PUT, DELETE http://example.com/users/{user_id}{.format}
    edit           edit_user     GET              http://example.com/users/{user_id}/edit{.format}
    articles       user_articles GET, POST        http://example.com/users/{user_id}/articles{.format}
      {article_id} user_article  GET, PUT, DELETE http://example.com/users/{user_id}/articles/{article_id}{.format}

Navigation

Chaining, indexing, following relationships:

>>> print app.users['dojo'].edit
http://example.com/users/dojo/edit

Positional and named parameters:

>>> print app.user_article('dojo', 'foo', format='json')
http://example.com/users/dojo/articles/foo.json

Parameter dictionaries:

>>> print app.user_article({'user_id': 'dojo', 'article_id': 'foo', format: 'json'})
http://example.com/users/dojo/articles/foo.json

Parameter inheritance:

>>> app = open_app('http://example.com/users/', format='json')
>>> print app.users['dojo'].articles['foo']
http://example.com/users/dojo/articles/foo.json

HTTP and JSON interfaces

HTTP interface::

>>> response = app.users['dojo'].articles['foo'].get(expected_status=200)
>>> response = app.users['dojo'].articles['foo'].put(body, expected_status=302)

Converting JSON content::

>>> app = open_app('http://example.com/users/', format='json')
>>> article = app.users['dojo'].articles['foo'].get(expected_status=200).parsed
>>> article['title'] = 'Updated!'
>>> response = app.users['dojo'].articles['foo'].put(article, expected_status=302)

REQUIREMENTS

AUTHOR AND CONTACT INFORMATION

Mike Burrows (asplake), email mailto:mjb@asplake.co.uk, website positiveincline.com (see articles tagged path-to)

APPENDIX - SAMPLE METADATA

templates =  [
      {
          'name':               'users',
          'uri_template':       'http://example.com/users{.format}',
          'optional_params':    ['format'],
          'options':            ['GET', 'POST'],
          'resource_templates': [
              {
                  'name':               'new_user',
                  'rel':                'new',
                  'uri_template':       'http://example.com/users/new{.format}',
                  'optional_params':    ['format'],
                  'options':            ['GET'],
              },
              {
                  'name':               'user',
                  'uri_template':       'http://example.com/users/{user_id}{.format}',
                  'params':             ['user_id'],
                  'optional_params':    ['format'],
                  'options':            ['GET', 'PUT', 'DELETE'],
                  'resource_templates': [
                      {
                          'name':            'edit_user',
                          'rel':             'edit',
                          'uri_template':    'http://example.com/users/{user_id}/edit{.format}',
                          'params':          ['user_id'],
                          'optional_params': ['format'],
                          'options':         ['GET']
                      },
                      {
                          'name':            'user_articles',
                          'rel':             'articles',
                          'uri_template':    'http://example.com/users/{user_id}/articles{.format}',
                          'params':          ['user_id'],
                          'optional_params': ['format'],
                          'options':         ['GET', 'POST'],
                          'resource_templates': [
                              {
                                  'name':               'user_article',
                                  'uri_template':       'http://example.com/users/{user_id}/articles/{article_id}{.format}',
                                  'params':             ['user_id', 'article_id'],
                                  'optional_params':    ['format'],
                                  'options':            ['GET', 'PUT', 'DELETE']
                              }
                          ]
                      }
                  ]
              }
          ]
      }
  ]

Updated