docs/quickstart.rst
Quickstart
==========
Let's start building a client for users resource in https://reqres.in/ service::
>>> # import API
>>> from simple_rest_client.api import API
>>> # create api instance
>>> api = API(
... api_root_url='https://reqres.in/api/', # base api url
... params={}, # default params
... headers={}, # default headers
... timeout=2, # default timeout in seconds
... append_slash=False, # append slash to final url
... json_encode_body=True, # encode body as json
... )
>>> # add users resource
>>> api.add_resource(resource_name='users')
>>> # show resource actions
>>> api.users.actions
{'list': {'method': 'GET', 'url': 'users'}, 'create': {'method': 'POST', 'url': 'users'}, 'retrieve': {'method': 'GET', 'url': 'users/{}'}, 'update': {'method': 'PUT', 'url': 'users/{}'}, 'partial_update': {'method': 'PATCH', 'url': 'users/{}'}, 'destroy': {'method': 'DELETE', 'url': 'users/{}'}}
>>> # list action
>>> response = api.users.list(body=None, params={}, headers={})
>>> response.url
'https://reqres.in/api/users'
>>> response.method
'GET'
>>> response.body
{'page': 1, 'per_page': 3, 'total': 12, 'total_pages': 4, 'data': [{'id': 1, 'first_name': 'george', 'last_name': 'bluth', 'avatar': 'https://s3.amazonaws.com/uifaces/faces/twitter/calebogden/128.jpg'}, {'id': 2, 'first_name': 'lucille', 'last_name': 'bluth', 'avatar': 'https://s3.amazonaws.com/uifaces/faces/twitter/josephstein/128.jpg'}, {'id': 3, 'first_name': 'oscar', 'last_name': 'bluth', 'avatar': 'https://s3.amazonaws.com/uifaces/faces/twitter/olegpogodaev/128.jpg'}]}
>>> response.headers
{'Date': 'Sat, 15 Apr 2017 21:39:46 GMT', 'Content-Type': 'application/json; charset=utf-8', 'Transfer-Encoding': 'chunked', 'Connection': 'keep-alive', 'X-Powered-By': 'Express', 'Access-Control-Allow-Origin': '*', 'ETag': 'W/"1be-q96WkDv6JqfLvIPiRhzWJQ"', 'Server': 'cloudflare-nginx', 'CF-RAY': '35020f33aaf04a9c-GRU', 'Content-Encoding': 'gzip'}
>>> response.client_response.cookies
<RequestsCookieJar[Cookie(version=0, name='__cfduid', value='d85187baf0752d02c6836abf7fb0c426c1506866165', port=None, port_specified=False, domain='.reqres.in', domain_specified=True, domain_initial_dot=True, path='/', path_specified=True, secure=False, expires=1538402165, discard=False, comment=None, comment_url=None, rest={'HttpOnly': None}, rfc2109=False)]>
>>> response.status_code
200
>>> # create action
>>> body = {'name': 'morpheus', 'job': 'leader'}
>>> response = api.users.create(body=body, params={}, headers={})
>>> response.status_code
201
>>> # retrieve action
>>> response = api.users.retrieve(2, body=None, params={}, headers={})
>>> response.status_code
200
>>> # update action
>>> response = api.users.update(2, body=body, params={}, headers={})
>>> response.status_code
200
>>> # partial update action
>>> response = api.users.partial_update(2, body=body, params={}, headers={})
>>> response.status_code
200
>>> # destroy action
>>> response = api.users.destroy(2, body=None, params={}, headers={})
>>> response.status_code
204
>>> # close client connections
>>> api.close_client()
Building async client for users resource in https://reqres.in/ service::
>>> # import asyncio, API and AsyncResource
>>> import asyncio
>>> from simple_rest_client.api import API
>>> from simple_rest_client.resource import AsyncResource
>>> # create api instance
>>> api = API(
... api_root_url='https://reqres.in/api/', # base api url
... params={}, # default params
... headers={}, # default headers
... timeout=2, # default timeout in seconds
... append_slash=False, # append slash to final url
... json_encode_body=True, # encode body as json
... )
>>> # add users resource
>>> api.add_resource(resource_name='users', resource_class=AsyncResource)
>>> async def main():
... print(await api.users.list())
... # close client connections
... await api.aclose_client()
...
>>> loop = asyncio.get_event_loop()
>>> loop.run_until_complete(main())
Response(url='https://reqres.in/api/users', method='GET', body={'page': 1, 'per_page': 3, 'total': 12, 'total_pages': 4, 'data': [{'id': 1, 'first_name': 'george', 'last_name': 'bluth', 'avatar': 'https://s3.amazonaws.com/uifaces/faces/twitter/calebogden/128.jpg'}, {'id': 2, 'first_name': 'lucille', 'last_name': 'bluth', 'avatar': 'https://s3.amazonaws.com/uifaces/faces/twitter/josephstein/128.jpg'}, {'id': 3, 'first_name': 'oscar', 'last_name': 'bluth', 'avatar': 'https://s3.amazonaws.com/uifaces/faces/twitter/olegpogodaev/128.jpg'}]}, headers={'Date': 'Mon, 26 Jun 2017 19:03:04 GMT', 'Content-Type': 'application/json; charset=utf-8', 'Transfer-Encoding': 'chunked', 'Connection': 'keep-alive', 'Set-Cookie': '__cfduid=d0412e4ebb0c5c29b09c0f756408d6ccb1498503784; expires=Tue, 26-Jun-18 19:03:04 GMT; path=/; domain=.reqres.in; HttpOnly', 'X-Powered-By': 'Express', 'Access-Control-Allow-Origin': '*', 'ETag': 'W/"1be-q96WkDv6JqfLvIPiRhzWJQ"', 'Server': 'cloudflare-nginx', 'CF-RAY': '37526caddd214af1-GRU', 'Content-Encoding': 'gzip'}, status_code=200)
Now, building a client for github events resource (https://developer.github.com/v3/activity/events/)::
>>> # import API and Resource
>>> from simple_rest_client.api import API
>>> from simple_rest_client.resource import Resource
>>> # create EventResource with custom actions
>>> class EventResource(Resource):
... actions = {
... 'public_events': {'method': 'GET', 'url': 'events'},
... 'repository_events': {'method': 'GET', 'url': '/repos/{}/{}/events'},
... 'repository_issues_events': {'method': 'GET', 'url': '/repos/{}/{}/issues/events'},
... 'public_network_events': {'method': 'GET', 'url': '/networks/{}/{}/events'},
... 'public_organization_events': {'method': 'GET', 'url': '/orgs/{}/events'},
... 'user_received_events': {'method': 'GET', 'url': '/users/{}/received_events'},
... 'public_user_received_events': {'method': 'GET', 'url': '/users/{}/received_events/public'},
... 'user_events': {'method': 'GET', 'url': '/users/{}/events'},
... 'public_user_events': {'method': 'GET', 'url': '/users/{}/events/public'},
... 'organization_events': {'method': 'GET', 'url': '/users/{}/events/orgs/{}'},
... }
...
>>> # set default params
>>> default_params = {'access_token': 'valid-token'}
>>> # create api instance
>>> github_api = API(
... api_root_url='https://api.github.com', params=default_params,
... json_encode_body=True
... )
>>> # add events resource with EventResource
>>> github_api.add_resource(resource_name='events', resource_class=EventResource)
>>> # show resource actions
>>> github_api.events.actions
{'public_events': {'method': 'GET', 'url': 'events'}, 'repository_events': {'method': 'GET', 'url': '/repos/{}/{}/events'}, 'repository_issues_events': {'method': 'GET', 'url': '/repos/{}/{}/issues/events'}, 'public_network_events': {'method': 'GET', 'url': '/networks/{}/{}/events'}, 'public_organization_events': {'method': 'GET', 'url': '/orgs/{}/events'}, 'user_received_events': {'method': 'GET', 'url': '/users/{}/received_events'}, 'public_user_received_events': {'method': 'GET', 'url': '/users/{}/received_events/public'}, 'user_events': {'method': 'GET', 'url': '/users/{}/events'}, 'public_user_events': {'method': 'GET', 'url': '/users/{}/events/public'}, 'organization_events': {'method': 'GET', 'url': '/users/{}/events/orgs/{}'}}
>>> # public_events action
>>> response = github_api.events.public_events(body=None, params={}, headers={})
>>> response.url
'https://api.github.com/events?access_token=valid-token'
>>> response.method
'GET'
>>> # repository_events action
>>> response = github_api.events.repository_events('allisson', 'python-simple-rest-client', body=None, params={}, headers={})
>>> response.url
'https://api.github.com/repos/allisson/python-simple-rest-client/events?access_token=valid-token'
>>> response.method
'GET'
>>> # close client connections
>>> api.close_client()
Create API without certificate validation
>>> # import API
>>> from simple_rest_client.api import API
>>> # create api instance
>>> api = API(
... api_root_url='https://develop-environment-with-self-signed-certificate.in/api/', # base api url
... params={}, # default params
... headers={}, # default headers
... timeout=2, # default timeout in seconds
... append_slash=False, # append slash to final url
... json_encode_body=True, # encode body as json
... ssl_verify=False # ignore verifying the ssl
... )
Check `https://github.com/allisson/python-simple-rest-client/tree/master/examples <https://github.com/allisson/python-simple-rest-client/tree/master/examples>`_ for more code examples.