dsync-sdk 0.1.2

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
Description: DSYNC Python SDK
========================

Python SDK for realtime synchronization with DSYNC

Overview
-----------------
The DSYNC Python SDK is a quick start bundle for developers who are interested in connecting 3rd party systems with the DSYNC platform. By crafting an external connector based on the SDK, your system will be automatically able to exchange data in near real-time with vast array of different systems, APIs, and databases already available on the DSYNC platform.

Near real-time data exchange between DSYNC and 3rd party system uses the secured http protocol. The external connector you need to build is essentially a RESTful API able to receive and send http requests from and to the DSYNC platform only. Some systems may have an existing API which you can simply extend and bend to the DSYNC specification or you may need to build one from scratch.

You don't have to be concerned with all the different APIs disparate systems may have – that's DSYNC's responsibility. All you need to build is the communication channel between your system and the DSYNC platform.

Authentication
-----------------
DSYNC platform uses API keys for communication with 3rd party systems. You can create a new API key from within your DSYNC account by going into "My Account" section. Treat this key as a password. Anyone with the key can send/receive data on your behalf. As there is no expiration set for API keys, it is highly recommended to rotate the API key every so often to prevent unauthorised access.

The API key must be sent with every request you make to the DSYNC platform. Your connector must be able to store this key and send it in 'Auth-Token' header along with the request data. If you fail to send valid API key the DSYNC platform responds with 401 Unauthorized. The DSYNC Python SDK will add the headers for you when you set the authorization token on the request.

Glossary
-----------------

Data Layout
~~~~~~~~~~~~~~~~~~~~~~

Schema in JSON format which defines one or more endpoints and all their respective fields. Generated by you in 3rd party system and sent to DSYNC.

For DSYNC to build and display a new system correctly on the canvas, the data layout which your connector generates must define at least one entity and the entity must have at least one field (eg. Product entity with SKU field).

Endpoint/Entity
~~~~~~~~~~~~~~~~~~~~~~

A single resource/object inside the 3rd party system. (eg. Product).

Field
~~~~~~~~~~~~~~~~~~~~~~

An attribute of an entity (eg. SKU)

API Key
~~~~~~~~~~~~~~~~~~~~~~

(aka Auth Token) Password used to authenticate http requests between 3rd party system and the DSYNC platform

Entity Token
~~~~~~~~~~~~~~~~~~~~~~

(aka Endpoint Token) Unique identifier of an endpoint generated by 3rd party system and sent to DSYNC in data layout. System scope – must be unique.

Treekey
~~~~~~~~~~~~~~~~~~~~~~

Uniquely identifies position of a single field inside an entity schema. Uses object dot notation. Entity scope – must be unique.

Getting Started
-----------------

- Create a DSYNC account (https://www.dsync.com/pricing)
- Create an auth token in the created account to use with the SDK
- Create consumable endpoint to generate datalayout for the DSYNC application (see below)
- Install a DIY system on your DSYNC dashboard

Full account setup instructions can be found at the Developer Portal (https://dsyncsdk.docs.apiary.io/reference/diy-connector)

API Documentation
-----------------
Full API documentation can be found at the Developer Portal (https://dsyncsdk.docs.apiary.io/reference/source)

Installation
-----------------
Install this package with pip:

pip install dsync-sdk

Requests
-----------------
Create a request using the RealtimeRequest object. You can add authentication and endpoint token (that was set in the datalayout) along with the data before making the request.

Example realtime "Create" request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
import dsync

data = {'foo': 'bar'}

# create a new realtime request object with your authorization token and endpoint token
request = dsync.RealtimeRequest('yourAuthToken', 'yourEndpointToken')
result = request.create(data)


Example realtime "Create" request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
import dsync

data = {'foo': 'bar'}

# create a new realtime request object with your authorization token and endpoint token
request = dsync.RealtimeRequest('yourAuthToken', 'yourEndpointToken')
result = request.update(data)


Example realtime "Delete" request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
import dsync

data = {'foo': 'bar'}

# create a new realtime request object with your authorization token and endpoint token
request = dsync.RealtimeRequest('yourAuthToken', 'yourEndpointToken')
# use your primary key for the entity you wish to delete as defined by the datalayout
result = request.delete('primaryKeyAsDefinedInDatalayout')

Responses
-----------------
All realtime methods will throw a RealtimeRequestException on error or return an dict of data if successful.

Datalayout Utils
-----------------
The Python SDK comes with some utils to generate the layout and tokens for each endpoint.
The DSYNC application must be able to consume your generated datalayout. For further details please see the Developers Portal (https://dsyncsdk.docs.apiary.io/#reference/destination/data-layout/get-data-layout)

Example of generating a datalayout array
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Build the fields first and add them to the endpoint objects.
Add the endpoint objects to the datalayout object before running the 'generate' method.

.. code-block:: python
import dsync

# create a new field object and set field information
# a list of field type constants can be found in the dsync.data_layout.Field class
field = dsync.Field({
'primary_key': True,
'required': True,
'treekey': 'product.sku',
'description': 'A product SKU',
'name': 'sku',
'type': dsync.Field.TYPE_TEXT
})

# create a new endpoint object and set endpoint information
endpoint = dsync.Endpoint({
'entity_name': 'product',
'treekey': 'product',
'entity_token': 'source-1-product-b5503a0ae5f3bc01b6a2da68afd33305',
'endpoint_url': '/entity/product'
})

# add field to endpoint
endpoint.add_field(field)


# finally create a new datalayout object
data_layout = dsync.DataLayout()

# add all endpoints and call the generate method
data_layout.add_endpoint(endpoint)

# create response
response = {
'status': 200,
'message': 'OK',
'detail': '',
'data': data_layout.generate()
}

# return response on call

Example of generating an entity token
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python
import dsync

entity_token = dsync.generate_entity_token('product')
# create a new endpoint object and set endpoint information

endpoint = dsync.Endpoint({
'entity_name': 'product',
'treekey': 'product',
'entity_token': entity_token,
'endpoint_url': '/entity/product'
})

#save entity_token to make requests at a later time


Running developer coding standards and tests
---------------------------------------------------
Install packages with pip:
.. code-block:: python

pip install -e .

Run tests:
.. code-block:: python

nosetests tests


Keywords: dsync,sdk,api
Platform: UNKNOWN
Classifier: Development Status :: 5 - Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Communications
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Requires-Python: >=2.6, !=3.0.*, !=3.1.*, !=3.2.*, <4