A Python wrapper for communicating with the Dorcas API
Project description
Dorcas Python3 SDK
A Python library for interacting with the Dorcas API. It makes it easy to access the API services directly from your Python project.
Example Usage
from dorcas_sdk_python import Sdk
client_id = 'jAGOn0aygL'
client_secret = '7CDouHd526pbPubv4fFLRnw5uWjKeaIh0ymsjJ39'
sdk = Sdk(client_id, client_secret, environment='local')
plans = sdk('resource', 'Plan')
plans.add_query_param('search', 'Pre')
response = plans.send('get')
response = response.send(method='post')
if response.is_successful():
print(response.data())
else:
print('Something went wrong')
Overview
- Getting Started
- Using the Package
- The
Sdk
object - Authentication
- Making Requests
- The
DorcasResponse
object
Getting Started
To get started, the first thing you need to do is create a developer account on the
Dorcas developer site.
You should follow the instructions inside the documentation.
Using the Package
The package was built to simplify the process of communicating with the API, and using it can be
summed up into 5 steps (excluding import
statements):
- Instantiate the SDK
- Create the
Resource
, orService
instance - Set your payload (
body
, orquery
) - Send the request, and receive a
DorcasResponse
instance as the return value - Use the
DorcasResponse
object
Below is an example:
from dorcas_sdk_python import Sdk
sdk = Sdk('jAGOn0aygL', '7CDouHd526pbPubv4fFLRnw5uWjKeaIh0ymsjJ39', environment='local') # step 1
password_login = sdk('service', 'PasswordLogin') # step 2
password_login.add_body_param('username', 'fakeid@gmail.com') # step 3
password_login.add_body_param('password', 'awesome secure uncrackable password') # step 3
response = password_login.send(method='post') # step 4
if response.is_successful(): # step 5
print('Access Token: {}'.format(response.access_token))
else:
print('Login failed')
print(response.errors()[0])
The Sdk
object
The Sdk
class allows you to set your API authentication details:
client_id
client_secret
It also allows you to choose an environment, you should either set it to:
- production : for the live Dorcas API
- staging: for the Dorcas testing API
The environment you choose decides which endpoint your requests are sent to.
Model Types
There are 2 kinds of models represented on this library, they are:
-
Resource
(s): these kind of models almost always require the call to be authenticated. They usually point to database records. This meansResource
models are always mapped to database records. E.g.Product
maps toProduct
records on the API -
Service
(s): these kind of models usually refer to things that aren;t actually records in the database as you'd expect. For instance, thePasswordLogin
service is strictly used for authenticating a user.
The Sdk
object makes it easy to instantiate these models; it can be done manually as well. To instantiate a model,
you do like so:
from dorcas_sdk_python import Sdk
sdk = Sdk('jAGOn0aygL', '7CDouHd526pbPubv4fFLRnw5uWjKeaIh0ymsjJ39', environment='local')
resource = sdk('resource', 'ResourceModelClassName') # we use the Sdk instance object
service = sdk('service', 'ServiceModelClassName')
All Resource
models extend the base Resource
class, while Service
models extend the base Service
class.
NOTE: When instantiating the models, you can also pass in additional keyword parameters
to the call, and they'll
also be passed to the constructor of the model class, and are collected in an option
property on the instance.
You can make the call like so:
from dorcas_sdk_python import Sdk
sdk = Sdk('jAGOn0aygL', '7CDouHd526pbPubv4fFLRnw5uWjKeaIh0ymsjJ39', environment='local')
resource = sdk('resource', 'ResourceModelClassName', length=5, tag='general') # we use the Sdk instance object
service = sdk('service', 'ServiceModelClassName', name='growth hacking')
print(resource.option.tag) # general
print(service.option.name) # growth hacking
This is useful for situations where you create your own custom Service
, or Resource
classes.
Authentication
Most of the calls to the API require the caller to be authenticated; this mean, it must contain a
valid access_token
for the user you're making the call on behalf of.
There are 2 ways to get a token:
- Via the login (
PasswordLogin
service) activity (public - available to all API clients) - Via direct authentication (private - only available to select clients)
Because these activities always follow the same process, 3 utility methods were provided to simplify these
calls (see the helpers.py
module):
authorize_via_email_only
: direct authorizationlogin_via_password
: username + password combination authenticationcreate_account
: although not part of this, but this function was provided to make user registration as simple as a function call
Authentication calls always provide a response similar to this:
{
"token_type": "Bearer",
"expires_in": 31536000,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjE1YTI3ZmY1ZWI0ZWNhZTczMjNhZWI2MjYwNjhkYzYyYTcxNzIwOTY2NzAwNzYxNDlhMzI1NTFjZjdlZDBkNjY4NWVkODVmYjA5NDMwNzExIn0.eyJhdWQiOiIyIiwianRpIjoiMTVhMjdmZjVlYjRlY2FlNzMyM2FlYjYyNjA2OGRjNjJhNzE3MjA5NjY3MDA3NjE0OWEzMjU1MWNmN2VkMGQ2Njg1ZWQ4NWZiMDk0MzA3MTEiLCJpYXQiOjE1MTUyNzc2MDksIm5iZiI6MTUxNTI3NzYwOSwiZXhwIjoxNTQ2ODEzNjA5LCJzdWIiOiIxIiwic2NvcGVzIjpbIioiXX0.GIBH8fuEg7bnSjm0Z3NtxuYshJ4RJVEcH-bNJPAMokLVvNSsMr4DBnYIsmJFk14pdMfiGRLqKQEZN2REgxTPj8q5a1btJwFoHqu5-nLcNGlrIKav8W8D5RtO8PZ1MHEBp-eyvu3U3-qIWe-vYan7csNdhnA0vcoZCXMU7JbAnATtahv0VjCqLo2n-VmICtYBvKfQjX3rVtp6sg4LqiChvGLDC5XoA0AYUfZdj2RvCj4oj0eC3W0y4ndcMpWkSSI1BIhZ9LyE6YloE0NNs4FB0upDoBVK_vxmwahdYsYaRgYGwu1RJf4v7hkLBvrSgwewqwTytCtfVU18EW71Pera9e9OMh1-ldZ3PiQMpBesos_bR9U2roEqfHUwJEY_1834hqiPQj_vq7E5ppMAVoWT2A9JMQIDzgZrxP7E0mynEoVohSBEvsF5VJxuUii8STcmGTo33x2dcMUYLtVNyRXHLzKjyYns_SrDtyIhyPrpYCtVNUWok_stLps6KrJFm7kJ0JB3u5-7tTP645DhPKaoMUrrodghZpkeCc_gabXtvughYgJkhlK3wixLCB1tdqR8IeuCdhWmqc31TfpfUob1Deka_jzmfxsyuu1VvIPiqdtw_Mm3RR6qQWhqfXQlpdf46SRa_lRveiOp7IXwPUFm_XSgSt8zBL5oQOm3k6r5lJo",
"refresh_token": "def50200ffed0e36ba02030192de5ecf0fa7b098e774ee3854c0a1d2a9b5e376d410aa435bf101fadbfd54a169a1c17a68ed27d242339c13dc318a7cb258d4ae2bcc487d0e7e9597794240bd51b24fce8ed274c55f368c0bdf8a739ceaa4e0656575de854152ba6c98126dd6b8435145d9e9d79df5bbe5114ca3da1c157447dc062be9c0cea747edfa9202f3ae036d65a532588ce91975db489c9721e53017b5b9069c5a13f51b682f5938a838dec60fb28f8ef19f62657f5f25082a376e14808f1963c1d2abd0af04a3d3a45c4e7abad8aba5b71f0245365530445a1a089604e727bce80be03ff2a24a094dc9acc22146108f3ee1e1f7efc11573c7b58e2ecc9c81241da90a0a477aeb784147c62e991b1630d07d8d9fb4ba1fc6d843408d268454c242153b04648ed9a1d8d9cf06aeeee59e33de8db4d06a569e5a9b155999f0e68226fae133dc06a88064b25032605e2be0921b069596333b108e9d124fa1b4fd0105"
}
The response contains an access_token
key which you set on the Sdk
instance for future use like
so: sdk.auth_token = response.access_token
All calls after this using this Sdk
instance will send the appropriate Authorization
header in the request.
Things to take note of
You will likely have to save this access_token
in your cache / session so you don't have to authenticate the
user on each page reload.
The auth_token
can also be provided when instantiating the Sdk
like so:
sdk = Sdk('jAGOn0aygL', '7CDouHd526pbPubv4fFLRnw5uWjKeaIh0ymsjJ39', auth_token='...', environment='local')
Making Requests
Making requests is the final step after setting your payload. It only requires you to know 2 things:
- The request method: One of 'get', 'delete', 'post', or 'put'
- The requests path: Every model has a base path, but certain sub-resources might require you appending something to the path
An example of the second point is like so:
Customer
resource has a base path of/customers
- To get a single
Customer
model from the API, we need a path in the form:/customers/{id}
In the above case, our call to send()
will look like: resource.send('get', customer.id)
The DorcasResponse
object
The DorcasResponse
object provides some simple methods:
is_successful()
: returnsTrue
, orFalse
if the request came back successfully. i.e. The API call worked finecode()
: only useful when acode
key exists in the returned responsemessage()
: useful when amessage
key exists in the returned responseerrors()
: will usually be a list of errors, whenis_successful()
isFalse
data()
: for successful responses with adata
key.
From above, you can see that all the methods excluding is_successful()
simply provide access to the keys in the
response. For keys
that don't have a defined method, you can access them like properties on the response object.
see Authentication for the example of accessing the access_token
key.
To-DO
- Add file upload support
Questions?
Just drop me a line at emmanix2002 [at] gmail dot com
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for dorcas_sdk_python-0.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2030f544596bb455c680f8ce7cf15223ce3d0e491763425b3a11bddcaf65d3ad |
|
MD5 | f3cfc2f40430c3163313b185610f91d5 |
|
BLAKE2b-256 | 853684a2b78581bb63d2c043acda2219bcab96808950f1dad7449b961818f757 |