A Python wrapper for communicating with the Dorcas API
pip install dorcas-sdk-python==0.0.1
A Python library for interacting with the Dorcas API. It makes it easy to access the API services directly from your Python project.
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')
Sdk
objectDorcasResponse
objectTo 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.
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):
Resource
, or Service
instancebody
, or query
)DorcasResponse
instance as the return valueDorcasResponse
objectBelow 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])
Sdk
objectThe 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:
The environment you choose decides which endpoint your requests are sent to.
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 means Resource
models are always mapped to database records.
E.g. Product
maps to Product
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, the PasswordLogin
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.
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:
PasswordLogin
service) activity (public - available to all API 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 callAuthentication 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.
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 is the final step after setting your payload. It only requires you to know 2 things:
An example of the second point is like so:
Customer
resource has a base path of /customers
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)
DorcasResponse
objectThe DorcasResponse
object provides some simple methods:
is_successful()
: returns True
, or False
if the request came back successfully. i.e. The API call worked finecode()
: only useful when a code
key exists in the returned responsemessage()
: useful when a message
key exists in the returned responseerrors()
: will usually be a list of errors, when is_successful()
is False
data()
: for successful responses with a data
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.
Just drop me a line at emmanix2002 [at] gmail dot com