API Documentation

 

 

Qalcwise API

 

List of API endpoints:

  • /api/token - Creates an Access Token for given user.
  • /api/record - CRUD for records in definitions.
  • /api/app - Distributing applications to users and enables user to execute defined and named WorkFlow actions on a given instance of the application.

 

Basics and Authentication

STANDARDS:

  1. Data Types:

    Date data types supported by API are Date, DateTime and DateTimeUTC:

    Date is passed like:
      value : "2012-04-23"

    DateTime is passed like:
      value : "2014-05-19T18:25:43.511"

    DateTimeUTC is passed like:
      value : "2012-04-23T18:15:43.511Z"

    The format used has to be inline with the field definition.
    All other date formats will be treated as Strings.

    Boolean Values are passed like:
      value : true
      value : false

    Numbers are passed like:
      value : 22
      value : 3.141592

    Strings are passed like:
      value : "some text"

  2. Basic Response: 

    If the response is different than GET and error is not a default(for example when resource is not found, or the Token is not provided) API error the json is returned. It always contains:

    {
      IsSuccess: Boolean,
      ErrorMessage: String
    }

    If the request was successful the "IsSuccess" is set TRUE.

    If there are errors the "IsSuccess" is set FALSE, additionally there may be a custom message in "ErrorMessage" field.

  3. Basic Request:

    Each API request has to have "Authorization" header with value Token and "Content-Type" header with value "application-json".

    Content-Type: application/json
    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yM[...] 

     

IMPORTANT! Each Request to API has to meet the Basic Request requirement.

 

AUTHENTICATION:

  1. Obtaining a Token:

    POST /api/token - Endpoint responsible for authenticating provided credentials. The user has to POST x-www-form-urlencoded user credentials together with "grant_type" (for now only "password" grant type is supported):

    username:user@test.pl
    password:passWord123!
    grant_type:password

    Together with header:
    "Content-Type":"application/x-www-form-urlencoded"

    When User is authenticated successfully the endpoint returns the json containing "access_token", together with "token_type", who requested it and expiration information.

    {
      "access_token":                    "eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTM4NCJ9.eyJlbWFpbCI6ImFkbWluQHRlc3QucGwiLCJ1bmlxdWVfbmFtZSI6IkFkbWluaXN0cmF0b3IiLCJodHRwOi8vcWFsY3dpc2UvY2xhaW1zL2RiaWQiOiIxLUxpc3QtU1lTVVNFUi1BRE1JTkBURVNULlBMIiwicm9sZSI6WyIqT3duZXIiLCJBRE1JTklTVFJBVE9SUyIsIkFMTCIsIkRFU0lHTkVSUyIsIlVTRUxPQ0FMQVBQUyQiLCJBUEkiXSwiaXNzIjoiUWFsY3dpc2UiLCJhdWQiOiIqIiwiZXhwIjoxNDk5OTg0OTQzLCJuYmYiOjE0OTk5NDE3NDN9.u0PeBG5nDHnhVooXSQ_X_Rgq5riV4ybETs_7db6L8YcDLG3IMw6zprD--gQ7FqRC",
       "token_type": "bearer",
       "expires_in": 43199
    }

    "access_token" and "token_type" are the most important. They are used to create the Token value that should be stored by the Client using the API.

     

  2. Token creation:

    Concatenate values "token_type" with "access_token" from /api/token JSON response.

    IMPORTANT!: The "token_type" with "access_token" have to be space( " " ) separated.

    Example token:
    "bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTM4NCJ9.eyJlbWFpbCI6ImFkbWluQHRlc3QucGwiLCJ1bmlxdWVfbmFtZSI6IkFkbWluaXN0cmF0b3IiLCJodHRwOi8vcWFsY3dpc2UvY2xhaW1zL2RiaWQiOiIxLUxpc3QtU1lTVVNFUi1BRE1JTkBURVNULlBMIiwicm9sZSI6WyIqT3duZXIiLCJBRE1JTklTVFJBVE9SUyIsIkFMTCIsIkRFU0lHTkVSUyIsIlVTRUxPQ0FMQVBQUyQiLCJBUEkiXSwiaXNzIjoiUWFsY3dpc2UiLCJhdWQiOiIqIiwiZXhwIjoxNDk5OTg0OTQzLCJuYmYiOjE0OTk5NDE3NDN9.u0PeBG5nDHnhVooXSQ_X_Rgq5riV4ybETs_7db6L8YcDLG3IMw6zprD--gQ7FqRC"

    Token is the way that the user is authenticated and authorized on the server side. Each API Request which requires authentication has to have it as "Authorization" header.

     

API ENDPOINTS

 

Records API:

Contains all the basic CRUD functionality for records in definitions.

 

Method

Path

Description

 GET

 /api/record/{name}

 Get records from definition .

 GET

 /api/record/{name}/{recordID}

 Get single record from definition.

 DELETE

 /api/deleteallrecords/{name}

 Delete all records from definition.

 DELETE

 /api/record/{name}/{recordID}

 Delete single record from definition.

 DELETE

 /api/record/{name}

 Delete rows with given keys.

 POST

 /api/getrecords/{name}

 Get rows with given keys.

 POST

 /api/record/{name}

 Add records to definition.

 PUT

 /api/record/{name}

 Update records in definition.

 PUT

 /api/recordupsert/{name}

 Update or insert records in definition.

 

name - Name of the Definition we want to get records from

recordID - Unique ID of a record(can be a single value or composite).

 

Endpoints:

  1. Get records from Definition, can specify offset and limit.

     

    GET /api/record/{name}?offset=0&limit=0

     

    parameters:

    • name: offset

      optional: true

      type: integer >= 0

    • name: limit

      optional: true

      type: integer >=0

    Explanation:

    This Method is responsible for getting rows(records) from the given definition, either List or a Table. If no limit and no offset are specified the Response should contain all the rows stored within that definition.

    Offset parameter specifies how many initial records should be skipped.

    Limit parameter limits number of returned rows to given value.

    Both Parameters are optional and should have values bigger or equal 0.

     

    Example:

    GET /api/record/USER-LIST?offset=5&limit=10 - skipps first 5 records and gets next 10 from USER-LIST

     

     

  2. Get record by id.

     

    GET api/record/{name}/{recordID}

     

    Explanation:

    Gets the uniquely identifiable record from given definition and returns it as json.

    404 - record doesn’t exist

     

    Example:

    GET /api/record/USER-LIST/1

     

     

  3. Delete all records from definition.

     

    DELETE api/deleteallrecords/{name}

     

    Explanation:

    Deletes all the records that are currently in a definition with given name.

     

    Example:

    DELETE  /api/deleteallrecords/USER-LIST

     

     

  4. Delete single record.

     

    DELETE /api/record/{name}/{recordID}

     

    Explanation:

    Deletes an exact record identified by ID,  from definition with given name.

     

    Example:

    DELETE  /api/record/USER-LIST/1

     

     

  5. Delete selected rows.

     

    DELETE /api/record/{name}

     

    Explanation:

    This method needs a model which contains rows with single or composite keys for rows. Those rows that have matching records in a provided by {name} definition are removed.

     

    Model (Array of objects):

    [
      {

        "KeyField" : value,
        "KeyField2" : value2
      }
    ]

    key - name of the column containing key
    value - value of a key for given row and column

     

    Example:

    [
      {
        "TYPE" : 2,
        "NAME" : "valuableProduct"
      }
    ]

    DELETE /api/record/TEST-TABLE

     

    This will delete from TEST-TABLE the row with composite key(2,"valuableProduct")

    REMARK!: Not all values of columns for the row are necessary, it is enough to provide only row values of columns which are marked as keys.

     

     

  6. Get selected rows.

     

    POST /api/getrecords/{name}

     

    Explanation:

    This method needs a model which contains rows with single or composite keys for rows. Those rows that have matching records in a provided by {name} definition are returned in a JSON.



    Model (Array of objects):

    [
      {
        "KeyField" : value,
        "KeyField2" : value2
      }
    ]

     

    Example:

    [
      {
        "TYPE" : 1,
        "NAME" : "cheapProduct"
      },
      {
        "TYPE" : 2,
        "NAME" : "secondProduct"
      }
    ]

    POST /api/getrecords/TEST-TABLE

     

    Gets 2 rows from TEST-TABLE, with given ids, first row key(1, abc), second row key(11, abc)

     

     

  7. Add records.

     

    POST /api/record/{name}

     

    Explanation:

    Saves the records provided in the model to definition with {name}.

     

    Model (Array of objects):

    [
      {
        "KeyField" : value,
        "KeyField2" : value2,
        "Field" : value3
      }
    ]

    key - column name

     

    Example:

    [
      {
        "TYPE" : 2,
        "NAME" : "newProduct",
        "COUNT" : 331
      },
      {
        "TYPE" : 2,
        "NAME" : "newerProduct",
        "COUNT" : 241
      }
    ]

    POST /api/record/PRODUCTS

     

     

  8. Update records.

     

    PUT /api/record/{name}

     

    Explanation:

    Updates the records provided in the model. If the record is nonexistent it does NOT create it.

     

    Model:

    [
      {
        "KeyField" : value,
        "KeyField2" : value2,
        "Field" : value3
      }
    ] 

    The row to be updated is determined by the key values, they can not be updated. Only the other values which do not belong to the key are updated.

     

    Example:

    [
      {
         "TYPE" : 2,
         "NAME" : "newProduct",
         "COUNT" : 1337
       }
    ]

    PUT /api/record/PRODUCTS

     

    The row defined by composite key(2, "newProduct") will have updated non Key Column "count" value to  1337.

  9. Upsert (Update or Insert) records.

     

    PUT /api/recordupsert/{name}

     

    Explanation:

    Updates or inserts the records provided in the model. If the record is nonexistent it is created it, if it exists it is updated.

     

    Model:

    [
      {
        "KeyField" : value,
        "KeyField2" : value2,
        "Field" : value3
      }
    ] 

    For the records that exist, the row to be updated is determined by the key values, they can not be updated. Only the other values which do not belong to the key are updated. Records that do not exist are created and added to definition with {name}.

     

    Example:

    [
      {
         "TYPE" : 3,
         "NAME" : "someProduct",
         "COUNT" : 300
       }
    ]

    PUT /api/recordupsert/PRODUCTS

     

    If the record exists the row defined by composite key(3, "someProduct"), will have updated non Key Column "count" value to  300. However if the record does not exists it will be created instead.

App API:

Enables simple Application interaction in forms of, executing actions on instances and distributing applications to users.

 

Method

Path

Description

 POST

 /api/app/

 Distribute application to users.

 PUT

 /api/app/{appID}

 Execute action in application instance.

 

 

  1. Distribute application.

     

    POST /api/app

     

    Explanation:

    User can use this method to distribute the application to either one or many of the defined groups or to list of users by providing their emails. Application to be distributed is defined using a unique "Identifier", its name. Provided "InputParameters" will be passed as input parameters for each created instance of the application.

    User needs to have editor permissions in an app definition in order to be able to distribute it.

     

    Model:

    Identifier: String

    DestinationUsers: Array of [String] - optional

    DestinationGroups: Array of [String] - optional

    InputParameters:[
      {
        "ParameterName": Value
      }
    ]

    Examples:

    Distributing App with input parameters:

    {
      "Identifier" : "PARAMETERSTEST",
      "inputParameters" : {
        "INPUTBOOLEANVALUE" : true,
        "INPUTSTRINGTEXT" : "second parameter"
      },
      "DestinationGroups" : ["All"],
    }

    POST /api/instance

     

     

  2. Execute workflow Action.

     

    POST /api/app/{appID}

     

    Explanation:

    User can use this method to execute a defined workflow action. There are multiple requirements that have to be met to execute this. User needs to be an editor at current state. Current State has to have defined workflow step for the action trying to execute.

     

    Model:

    Action: String

     

    Action is the case sensitive name of the action we want to execute.
    {AppID} from URL  is an actual ID of an instance of application(can be viewed for example when visiting a saved instance of an application from the main stream, the ID is part of the url).

     

    Example:

    {
      "Action" : "actionname",
    }

    PUT /api/instance/1-App-TESTAPP-1-743bf042411c405d91588317c82d5c55



Masz więcej pytań? Wyślij zlecenie

0 Komentarze

Komentarze do artykułu są zablokowane.
Oparte na technologii Zendesk