Articles in this section

Syntax and Examples

Vine-Tuki
Follow

Syntax and Examples

Sample of a request:

https://vine.eu/api/rest/2.0/vy_person(302211548)/objectimage

- get the image file of the person with given id in binary format

 

About Syntax

https://vine.eu/api/rest/2.0/vy_person(302211548)/3(startdate>[$NOW])?top=10&order=startdate desc

Syntax:

base_url / resource [(value_conditions)] [/link] [(value_conditions)] [/field] [?params]

where

  • base_url – base URL of the service
  • resource - name of a vine table or a special resource. A resource and link(if present) is normally converted into the "FROM" part of an Oracle SQL
  • value_conditions - conditions filtering data. Normally converted into a "WHERE" part of an SQL
  • link - used to specify if a resource connected to the main given resource should be returned.
  • field - returned field. Only one field can be used and only one data row returned if field is used. All resource fields (available in an object view) are returned if field is not given.
  • params – parameters used to modify, limit or tune the returned set of data

About Base URL

Example:

https://vine.eu/api/rest/2.0/

Note: 2.0 – is the REST version here. It is always recommended to use the latest version of REST available.

Earlier versions of Vine REST had a different base_url as follows. It is not recommended to use those obsolete versions any longer.

http://vineyard:8080/vineyard/rest/v1.2

- requests with such base_url will be using the v1.2 version of REST

 

 

Note: Please note that all the code examples that will follow in the REST chapter will be without the base_url part.

Resources

resource - name of the table (VY_PERSON, VY_COMPANY, ...) or name of a special virtual resource - USER (currently logged user). Tables not linked with the VY_CONNECTION table (for example, parameter tables) can be queried but links can't be applied.

Example:

/vy_resource

returns all fields (except special) of all not deleted rows using vy_resource_view. The same as:

/vy_resource(status='B')

 

Please note that for most of resources, status='B' condition is used by default. You need to use the showDeleted parameter if you want to receive deleted rows.
However, the STATUS!='D' condition which returns statuses such as O,S,E, etc. is used by default for the following tables:

'VS_AUTOMATION_QUEUE'

'VS_REPLICATIONTARGETS'

'VY_CLIENTSQL'

'VY_OBJECT'

'VY_OBJECT_FIELD'

'VY_PACKAGE_VERSION'

'VY_TABLE'

'VY_TABLE_FIELD'

'VY_OBJECT_FIELD_VIEW'

'VY_OBJECT_VIEW'

'VS_AUTOMATION_QUEUE_VIEW'

'VY_CLIENTSQL_VIEW'

'VY_TABLE_VIEW'

 

Value Conditions

Value conditions are used to filter the returned data set.

value_conditions = id|{field_condition|link_condition}[{and|or}field_condition|link_condition]

where

  • id - object identifier (ID field).

    • /VY_EVENT(300166001)
    - gets event with specified ID. returns all fields except special ones

    Please note that direct object ID number has to be used. If it is not a direct id (for example, if ID is returned by a function) then you need to use a field condition (see below).

    For example, the following request will NOT work

    /vy_collection(GetSetting('vx_regEvents_collection'))

    - WRONG!

    You need to use a field condition:

    /vy_collection(id=GetSetting('vx_regEvents_collection'))

    - CORRECT


    At least 2 tables have additional 'virtual' ID fields. For example, there are no columns named 'id' in VY_USERSETTING, VY_DOCUMENTVERSION, and VY_SYNCACCOUNT. The service uses other columns as ID column for these tables as follows: SETTINGID for vy_usersetting, DOCUMENTID for VY_DOCUMENTVERSION, and ACCOUNTID for VY_SYNCACCOUNT.

  • field_condition = field_name { = | < | > |<= | >= | in } { value | expression }

    • where field_name – [name of the field], can be either in brackets or without: e.g. [name] or name

    value - constant value, expression - any expression supported by XMLQuery

    /VY_COMPANY(businessid='1234567-1')

    - get single company using the businessid field

     

  • link_condition = special syntax to check object connection$[connectionTypeId:connectedObjectId]. One of parameters should be provided.

    • If connectionTypeId skipped it means any connection type.

    Instead of connectedObjectId the following syntax can be used to get the id of the current user: [$user]

    /vy_company($[1:[$user]] OR $[1:300110962])

    returns companies which are employers of the current user or of a person with id=300110962

Note: Using the special syntax of link_condition is not recommended and its support may be discontinued. We recommend using the FilterConnection function.

Examples:

 

/VY_EVENT((startdate > MakeDate(GetYear([$now]), GetMonth([$now]), 1) and enddate > ([$now]+14)))

-returns events which happen in two weeks time from current month start

 

/VY_CONNECTION(fromobjectid=300061680 and connectiontype=11 and targetobjectid=306521737)

returns connection if the given company belongs to given collection.

 

Links

Links are used when it is needed to return a resource connected to the main resource.

link = [+|-] (link1_id, link2_id,...linkN_id) [( value_condition )] [ /link ]

where link_id - link identifier.

Direction of link is determined automatically by object type if it's possible ("from" and "target" object types differ). Else it should be set explicitly by [+|-].

Number of links can be unlimited.

In Vine database, types of links(also called connections) and their IDs are set in the vy_connectiontype table.

Examples:

 

/VY_EVENT(300166001)/4
- get person responsible( connection id = 4) for given event.

 

/user/4

get events for which the current user is responsible

 

/USER/1/16($[:[$user]])

- returns events connected to the user employer (with contype=16) and to the current user (with any connection).

 

/USER/3(startdate>([$now]-14))/4

- get events started no more than 14 days ago and connected to the user as attendee and then get persons responsible for these events

 

/USER/3,4(startdate>([$now]-14))

- get events connected to the user as attendee or responsible and then choose ones which started no more than 14 days ago

 

Fields

field - returned field.

  • returns always "binary file" = "application/octet-stream", does not respect the type requests (e.g.the XML or JSON request types)
  • can fetch only one field (requests like "person/name,lastname" are not allowed)
  • usually used to get binary data from the database and should be used only in special cases when, for example, downloading binary data.
  • returns only the first entity from the matched set.

Examples:

/VY_EVENTTYPE(-2)/NAME
- gets the name of VY_EVENTTYPE item with id=-2

/VY_PERSON(300001061)/OBJECTIMAGE
- get the photo of the person with given id in binary format

 

 

Parameters

Parameters are used to modify, limit or tune the returned set of data. The following parameters are supported currently:

  • skip - number of skipped rows

    • /vy_company?skip=20&order=name asc
    -the resulting sequence first sorted by name, then 20 rows are skipped and companies starting from 21st are returned

     

  • top - number of returned rows

    • /vy_company?top=10&order=name asc
    -the resulting sequence first sorted by name, then 10 top companies are returned

     

  • order - sorting order. "asc" - ascending(default), "desc" - descending

    • /vy_company?order=name asc
    -the resulting sequence sorted by company name

     

    /vy_company?skip=20&top=10&order=name asc
    -the resulting sequence first sorted by name, then 20 rows are skipped and 10 companies starting from 21st are returned

     

  • showSpecial - returns special fields (blobs and xml fields), note that by default special fields are not returned. base64 encoding used for binary data when showSpecial is used.

    • /vy_company(314224172)?showSpecial

    - returns special fields, for example, binary objectimage, while /vy_company(314224172) does not return objectimage

     

  • $count - this parameter forces the query to return the size of the data selection instead of the data itself

    • /vy_person?$count

    - returns only the numbe rof persons in the database

     

  • idField - used for tables which do not have an ID field. REST assumes that there is an ID field in a database query result

    • /vy_table_field?idField=OOFID
    - this query will fail without idField

     

  • showDeleted - used to add deleted rows (rows with status='D') to request results. So a request with this parameter returns all rows having either status 'B' or 'D'.

    • /vy_resource?showDeleted

    - in addition to available resources (status='B') also returns deleted resouces (status'D')

    note that the following request won't work to return deleted objects /vy_resource(STATUS='D') (as by default the status='B' check is added)

     

  • translate - used to translate the NAME fields of requested data such as vine parameters, connection type names, collection names and so on. Only the NAME field is translated and fromname and targetname for connection types.
    Supported languages: en - English, fi - Finnish, ru - Russian.

    • /vy_eventtype?order=id&translate=fi

    - returns translated vy_eventtype parameter names ordered by ID

     

    /vy_eventtype(-3)?translate=fi

    - translates and returns parameter with id=-3

     

    /vy_connectiontype?translate=fi

    - returns translated connection type names

     

    /vy_collection(id= GetSetting('vx_Subscribe_MainCollection'))/-21?translate=fi

    - returns translated subscribe collection name

     

  • cache-refresh=1 - used to make sure that the very latest data is returned from the Vine database. For example, important in cases when the returned data is then shown to the user for editing.

    •  

Comments

0 comments

Please sign in to leave a comment.