l12: rest service

1

i-viewsUniversityPart12:RESTService

22

REST-Service

PatrickCloshen

SoftwareEngineer

intelligentviews gmbh

Today‘s Speaker

33

REST-Service

Agenda

1. Introduction

2. Set-up issues

3. Configuring services

4. Homework

44

REST-Service

1.Introduction

• Accessand edit the semantic graph database viaREST-Services

• Specify what can be seen and how it is displayed and edited viaview configurations

• Make use of pre-defined resources

• Compose the back-endpart for your own web-frontends

55

REST-Service

Architecture

mediator

Web-frontend

http/https

REST-bridges

internal/http

66

REST-Service

2.Set-up issues

• RESTcomponent:provides needed schema for services and resources• Needsto be added inthe Admin-Tool

• Configuration of front-ends:front-ends need to be connected to the bridges to render the served data

• Additionalsettings:your semantic graph database musthave auser typethat provides apasswordattribute.Thiswillbe set up if you choose auser typewithin the settings inthe knowledge builder,tab„system“,item„rights“(needed for authentication)

77

REST-Service

Set-up issues

• Configuration of REST-bridges:configuration file bridge.ini is needed to specify which services aregoing to be provided by the application

• Define the host[and port]of the server of the semantic graph database

• Define the name of the volume to be accessed

• Define the port over which the services willbe available

• Define the services this instance of REST-bridgeis going to serve

88

REST-Service

3.Configuring services

• Theinstallation of the RESTcomponent inthe semantic graph database provides schema for serviceand resource objects and installs the built-inresources

• Services• They bundle resources to differentiate between differentsets of capabilities as needed

• They need to be identified inthe configuration of the bridge(s)to be available

• Resources• They define what requests are available within the containing service (path)and how they are executed

• They define which HTTP-Method is used

• They declare whether to use authentication or not

• They define the parametrization of the request

99

REST-Service

TheRESTservice description

Listof RESTservices

Servicedetails

1010

REST-Service

Buildingblocks (RESTservice)

- Collectionof resources- Startof the URLpath- Servicesare configured inthe

bridge.ini

[Default]host=localhostloglevel=10

[KHTTPRestBridge]volume=Schulungsnetzport=8815services=music

1111

REST-Service

Buildingblocks (RESTresource)

- Remainder of the URL-path- MultipleTypes

- Scriptresource- Built-inresource- Static resource

- Defines apath-pattern- Partsin{curlyBrackets}are

placeholders for variables

1212

REST-Service

Buildingblocks (RESTmethod,script resources only)

HTTPmethod- GET,POST,PUT,DELETE…

Input/Outputmedia type- mime-types of accepted and

produced data

Script- JavaScriptthat is executed to

compute the response

Transaction- Read,Write,Controlled by

script

1313

REST-Service

Buildingblocks (RESTparameter)

Location(Style)- Path-variables- Query-parameters- HTTPheaders

Datatypes coercion- String,Integeretc.- Specialk:element

Repeating- ?album=abc&album=cde

Fixedvalue- default if parameter is absent

Required- Error,if parameter is absent

1414

REST-Service

Buildingaresource (Addaresource)

Theleft button always adds anewconfiguration object

1515

REST-Service

Buildingascript resource (Addamethod)


1616

REST-Service

Buildingascript resource (Selectamedia type)


1717

REST-Service

Buildingascript resource (Selectamedia type)


1818

REST-Service

Buildingascript resource (Createanew JavaScript)


1919

REST-Service



2020

REST-Service


Astub for the JavaScriptisgenerated

„parameters“are the RESTparameters defined inframework

2121

REST-Service

Buildingascript resource (Addaparameter)


2222

REST-Service

Buildingascript resource (Choose aparameter type)


2323

REST-Service

Buildingascript resource (Compute something)


2424

REST-Service

Buildingascript resource (Testthe script)


2525

REST-Service

Opening the request inthe browserhttp://localhost:8815/music/album/ID1405_147386337/songs

2626

REST-Service

Built-inResources

• Pre-defined resources that are available inthe system

• Canbe added to services

• Coveroften encountered use-cases:• Accessing and changing blob attributes

• Object lists of objects,including sorting and filtering

• Accessing print templates and rendering with specified objects

• Accessing the configured icons of types

• ViewconfigMapper uses 3types of built-inresources

2727

REST-Service

Built-inResources

Creating abuilt-inresource:

• Selectthe service into which the resource is to be embedded

• Clickonthe „Createnew Instances of RESTresource“button

• Choose „Instances of Built-inResource“

• Choose the desired kind of built-inResource• ActionResource

• BlobResource

• EditorConfigResource

• ObjectListPrintTemplateResource

• ObjectListPrintTemplateResourceWithFilename

• ObjectListResource

• TopicIconResource

2828

REST-Service

Built-inResources

/blob/{blobLocator}

Allowed methods:GET,POST,PUT

Parameters:

• blobLocator:e.g.id of the blob attribute whose contents are to be retrieved or set

• binaryKey:used inmulti-partmessages to identify the corresponding part of the data

• overrideContentType:tells the database what content typeit really has to expect

• uploadOnly:boolean which controls whether the data willonly be sent to the database,result is aJSONstring that allows to refer to the created blob and set it inanother RESTcall

Examples:

GEThttp://localhost:8815/default/blob/ID43_1234567 fetches ablob from i-views

PUThttp://localhost:8815/default/blob/PP~ID43_1234~ID45_2345creates anew blob atobject with first id ofproperty typewith second id (Possible PropertyLocatorsyntax)

2929

REST-Service

Builtin-inResources

/topicIcon/{topicID}

Allowed methods:GET

Parameters:

• topicID:(required)id of the object

• size:(optional)desired integerpixel size of the icon,expanded to point

• extensions:(optional)boolean,true allows returning icons of extension objects of the chosen topic

Examples:

GEThttp://localhost:8815/default/topicIcon/ID43_1234?size=10

3030

REST-Service

Built-inResources

/{typeLocator}/objectList

Allowed methods:GET

Parameters:

• typeLocator:(required)id of the typewhose objects are to be displayed intable form

• name:(opt.)name of the object list configuration to be used

• application:(opt.)name of the application which determines the view config

• elements:(opt.)comma-separated locators for elements for the table

• elementsPath:(opt.)kpath-expressionthat willbe used to determine start objects

• startTopic:(opt.)id of topic to use as starting point for elementsPath

• sort:(opt.)expression for sorting (multi-sort possible)

• filter:(opt.)expression for filtering steps

3131

REST-Service

Built-inResources

Parameterscont.:

• disableInheritance:(opt.)boolean to prevent descending into sub-types

• type:(opt.)string param to choose whether to display objects or sub-types of the given starting type

Remark:Although the parameter „application“is optionalit is essentialfor accessing the correct objectlist view configuration.Therefore always associate the table with the pre-defined application „REST“andadd the parameter „application=REST“to the request

Examples:

GEThttp://localhost:8815/Person/objectList?name=test&application=REST

render allpersons using object list config named „test“

GEThttp://localhost:8815/Person/objectList?sort=-1&filter=1~equals~g*

sort the table indescending order of values incolumn 1and filter with „g*“inthe first column

3232

REST-Service

Built-inResources

/{conceptLocator}/objectList/printTemplate/{templateLocator}

Allowed methods:GET

Parameters:

• sameas objectList before

• templateLocator:(required)id of the print template object to be used to generate the output

Examples:

GEThttp://localhost:8815/default/Person/objectList/printTemplate/ID_46_3456

render allPersonobjects using the referenced print template

3333

REST-Service

Built-inResources

/{conceptLocator}/objectList/printTemplate/{templateLocator}/{filename}

Sameas above,additionalparameter „filename“is notread,serves only to distinguish requests inthewebbrowser

3434

REST-Service

Built-inResources

Configuring the built-inresources:

• Built-inresources encapsulate specific functionality,the only thing left to configure is whether thisinstance of resource needs authentication

• Additionally built-inresources offer the capability to define scripts which are executed before andafterthe request is computed to allow for changes inadvance and to further influence the responsethat the request computed• Preprocessing Script

• Postprocessing Script

• Thesescripts are created and maintained analogous to the scripts that are embedded into script RESTresources,they only provide differentfunction headers

3535

REST-Service

Static FileResources

Static content can be referenced from within the RESTbridge.

• place content insub-directories of the installation directory of the RESTbridge

• declare the path pattern of the intended resources to map the relevantsub-directories

Example:

• installation directory of the bridge includes directory „icons“which contains the needed files

• create astatic file resource with path pattern „icons“,embed it into the service „test“

• request willlook likethis:

• GEThttp://localhost:8815/test/icons/file.png

3636

REST-Service

Homework

1. Define ascript-resource that accepts astring parameter and responds by returning the given string

2. Define ascript-resource that allows to edit anattribute of your choice atanobject• Parametersfor value anto identify the object that is going to be edited

• Method

• Transactioncontrol!

• Errorhandling (e.g.incase of attribute value typemismatch)

3. Define abuilt-inresource that returns anobject list of allsongs• Remember to refer the specified object list to the application RESTwith the relation „apply in“!

3737

Advanced:REST-Service

Sendyour questions to:[email protected]

Consultationhours:EveryWednesday

Thank you for visitingi-viewsUniversity

3838

Advanced:REST-Service

UnsereneuenIcons

l12: rest service

Data & Analytics