Pular para o conteúdo principal

FV Decipher Support

Todos os tópicos, recursos necessários para FV Decipher.

Base de Conhecimento da FocusVision

Decipher REST API 2.0

1: Overview

The Decipher REST API is the tool for Automating your workflow with the Decipher platform. It enables you to efficiently send and request resources to and from any project that you are working on.

The API uses the REST HTTP verbs along with abstraction to map the CRUD operations needed for creating, Accessing and modifying project, company or user data. For example, you can "Create" a new resource, "Read" a list of users, "Update" an existing user, and "Delete" a user. This allows for a clean, uniform API:

  • POST / users ==> Create new resource
  • GET / users ==> List of users
  • PUT / users / 1234 ==> Update data of user # 1234
  • DELETE / users / 1234 ==> Remove this specific user

Decipher The REST API is equipped with a Python library package que, once installed, Enables you to seamlessly integrate with the Decipher services you have access to and use.

2: Introduction to the Decipher REST API

The easiest way to get started with the Decipher REST API is to:

  1. Access the API by installing the Decipher REST API Python Library
  2. Login or generate an API key to authenticate with the API
  3. Make an API request

2.1: Accessing the API

To access the API, you'll want to download and install the Decipher API Python Library package. For customers with their own private server, this is installed by default. If you are accessing the API via some other Linux system, you can install the Decipher API Python library with the following command:

Sudo pip install decipher

This Python library includes a script named beaconque you can run from the command line to connect with the API easily.

Note: The beaconscript will be more comfortable to use than a tool like curl.

Once the library is installed, type "beacon" into your terminal shell to view its usage details.

user @ domain: ~ $ beacon 
beacon [options] <verb> <resource> [arg = value ...] 
Verb is one of: 
get - list resources 
post - create new resource 
put - update existing resource 
delete - delete or remove existing resource 
login - interactively define an API key and host 
rekey - rekey your current secret key and update the config file 

Extra arguments are decoded JSON objects / arrays if They start with {or [ 

-v verbose (show headers sent & received)) 
-t display output to an aligned text table 
-x display output IBM JSON XML 
-p display Python code required to make the call 
-s <section> use a different section in the / home / user / .config / decipher file than 'main' 
-V <version> use a different API version

2.2: Authentication & Authorization

The API will only respond to authorized users. To become authorized, you must first generate an API key that will be authenticated by the system.

For customers with their own private server, authentication happens automatically with your shell credentials if running the commands via the shell command line. There is no need to login with steps below.

Type "beacon login" into your shell terminal to view the methods for authenticating with the system.

user @ domain: ~ $ beacon login 
If you are using the Decipher API for automation, you shouldnt generate and enter 
an API key. If you only need temporary access, eg to upload / download files 
you can enter your username / password below 

How do you want to authenticate? 
1. Enter the 64-character API key (valid until deactivated) 
2. Enter your username / password (temporary login) 
3. Enter the long code (visible on the API key page) 
q. Quit 
Select 1, 2, 3 or q:

If you already have an API key, then you can use option 1 to store your API key for future use.

If you just want to explore the API, then you can use option 2 to temporarily login to the system using your normal username / password without creating an API key.

If you have access to a temporary API key, then you can use option 3 to store this temporary API key for temporary use. This method will only persist while your current session is active.

2.2.1: Generate an API Key from the Research Hub

To generate an API key, access the Research Hub and select "Access API" from the System Tools menu (click on your profile image / avatar).

Select "Create new API Key" and enter self to create a new API key for yourself.

If you already have an API key, then select "rekey" next to your email address to re-generate the existing API key you might have.

Note: Any user can generate an API key but their level of access is dependent on their user permissions.

2.2.2: Generate a Temporary API Key from the Research Hub

In the same area where you can generate an API key , there's Also an option to generate temporary key so That You can get started quickly with the API.

This API key will only persist and authenticate you while your current session is active.

2.3: Make an API Request

All API requests must happen over HTTPS with a base URL of /api/v1/.

For example, you might send a GET request to /api/v1/surveys/your/surveys/datato get data for your survey using the "Data Out" API.

2.3.1: Using the Decipher API Python Library

From the command line, you can run the beaconscript Which lets you quick run an API call:

Beacon -t get rh / users select = id, login, fullname, last_login_where sort = -last_login_where limit = 10

In the above example:

  1. An API call is made using the GET method
  2. It's targeting the "users" resources, which exists at / api / v1 / rh / users
  3. It's using the "projection" feature to select only 4 fields
  4. It's using the "sorting" feature to order the response by descending time of last login
  5. It's using the "pagination" feature to limit output to the first 10 entries
  6. It's using the "-t" option to output the data as a formatted text table, rather than JSON

More information can be found on the Decipher REST API Python Library page .

2.3.2: Using the Decipher API Python Library in a Python Script

The Decipher API Python Library can be used in a Python script for further customization and automation. In the above example, we replace the "-t" flag with the "-p" flag to get the equivalent code to run in a Python script.

Beacon -p get rh / users select = id, login, fullname, last_login_where sort = -last_login_where limit = 10
from decipher.beacon import api 

users = api.get ( "rh / users" select = "id, email, fullname, last_login_where" sort = "- last_login_where" limit = 10) 
for user in users: 
    print "User # {Id} <> logged in last from {last_login_where} ". Format (user)  

Note, if you are running this outside the Decipher private server (eg your own Linux machine), you will need to authenticate via one of the methods found under Authentication here .

2.3.3: Using cURL to Access the API

We recommend using the Decipher Python API Library to make API requests.

CURL All requests must include your API key in the x-apikeyheader. Using cURL, we can list all of the available, currently implemented API endpoints:

Curl --header "x-apikey: API_KEY_GOES_HERE" https://v2.decipherinc.com/api/v1/meta

The following command tests the "Hello Service" endpoint:

Curl -X GET --header "x-apikey: API_KEY_GOES_HERE" https://v2.decipherinc.com/api/v1/hello?name=FunFunFun

The above example returns the following JSON object:

{"Ok": "1", "hello": "FunFunFun"}

An example of a post command can be seen below. For this command we are passing the JSON object to the data in order of the data post.

Curl -X POST -H 'Content-Type: application / json' -H "x-apikey: MY_API_KEY" 'https: // HOST / api / v1 / surveys / SURVEY_PATH / data / edit' -d '{"data" : [{"Q1": 1}]} '

Note: When using JSON we must make sure we pass the content-type as well as use the proper syntax, which is to use double quotes around the various items within the JSON object.

Documentation for cURL can be found here .

2.3.4: Using Another Programming Language (eg C #, Java, PHP, etc.)

The Decipher REST API aims to support other programming languages ​​like C #, Java and PHP in the future, but only the Python 2.7.3 programming language is currently supported with pre-made libraries. However, the REST API only requires that you send HTTP requests and parse JSON documents - features are universally supported.

3: Decipher API Documentation & References

3.1: Decipher API Python Library Page

The documentation for the Decipher REST API Python package can be found here: https://pypi.python.org/pypi/decipher

3.2: Decipher API Documentation Reference Page

The Decipher REST API reference page can be found below. This link will include all current and future API resources available with the Decpiher REST API.

3.3: Response Codes & Error States

The following HTTP response codes are returned when making a request to the Decipher API:

Code Description
Your date is in the response body.
Your API key is invalid, expired, not valid from this IP address or for this action.
You have exceeded your monthly API calls.
Your API key is valid but you are not allowed access to this survey.
You asked for a survey or resource que does not exist.
You tried to eg DELETE something que does not support deletion.
Please wait a moment and try your request again.
Resources does not implement this method. Are you using GET / POST / PUT / DELETE?
Something else went wrong (eg survey can not be loaded due to an error).

The "402" response code is currently not used.

A complete error response will look like this:

HTTP / 1.0 401 invalid key. Verify the spelling of your key by Accessing the Research Hub 
Content-Length: 108 
Content-Type: application / json 

"$ error": ". Invalid key Verify the spelling of your key by Accessing the Research Hub", 
"$ code" : 401