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 a REST abstraction along with HTTP verbs to map the CRUD operations needed for creating, accessing and modifying project, company or user data. For example, you can "Create" a new user, "Read" a list of users, "Update" an existing user and "Delete" a user. This allows for a clean, uniform API:

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

The Decipher REST API is equipped with a Python library package that, 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 beacon that you can run from the command-line to connect with the API easily.

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

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

user@domain:~$ beacon
Usage:
 beacon [options] <verb> <resource> [arg=value...]
Verb is one of:
 get    -- list resources
 post   -- create new resource
 put    -- update existing resource
 delete -- delete or retire 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 as JSON objects/arrays if they start with { or [

Options:
 -v verbose (show headers sent & received))
 -t display output as an aligned text table
 -x display output as 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 should generate and enter
 an API key. If you only need temporary access, to e.g. 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 a 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 "API Access" 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.

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/data to 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 beacon script 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 example above:

  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 file for further customization and automation. In the example above, 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 a Decipher private server (e.g. 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 API Python Library to make API requests.

All cURL requests must include your API key in the x-apikey header. 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 example above 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 a JSON object as the data in order to do 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 (e.g. 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 can 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.
http://v2.decipherinc.com/s/local/beacon.html

3.3:  Response Codes & Error States

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

Code Description
200
SUCCESS
Your data is in the response body.
401
INVALID AUTHENTICATION
Your API key is invalid, expired, not valid from this IP address or for this action.
402
PAYMENT REQUIRED
You have exceeded your monthly API calls.
403
INVALID AUTHORIZATION
Your API key is valid but you are not allowed access to this survey.
404
NOT FOUND
You asked for a survey or resource that does not exist.
405
METHOD NOT ALLOWED
You tried to e.g. DELETE something that does not support deletion.
429
TOO MANY CONCURRENT REQUESTS
Please wait a moment and try your request again.
501
NOT IMPLEMENTED
Resources does not implement this method. Are you using GET/POST/PUT/DELETE?
400
OTHER
Something else went wrong (e.g. survey cannot be loaded due to an error).

The "402" response code is not currently 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
}