Data Sources
Configuring the ReST API data sources
The Data Sources configurator is available from the App Studio.
This is a data-driven business application and the data is sourced from ReST API requests which provide Create, Read, Update, Delete (CRUD) end-points to pull and push data between the back-end and the front-end.
HTTP Request Methods
We call a ReST API endpoint, a data source request. Each request will be one of the industry standard HTTP request methods (also known as verbs). The following are supported:
Retrieve one or more records from a server
Send data to a server to create/update a record
Send data to a server to create/update a record
Deletes the specified record on the server
Partial modifications of a record on the server
These coloured icons are used when configuring data source requests.
Configurator Popup Form
Opening the data sources from the app studio opens a modal popup form.
This shows a hierarchical tree view on the left with properties of the selected tree node on the right. Each of these panels has buttons to manage each data source. The tree view shows data sources, folders and requests.
WARNING: This modal dialogue automatically saves all changes i.e. there is no Apply or Cancel button. Follow best-practice which is to make changes slowly at a controlled pace and test your changes constantly.
Data Sources Panel
This panel has an add button menu and a clone button. The tree view shows the data source request hierarchy consisting of data sources, folders, sub-folders and data source requests. The tree view nodes can be dragged and dropped into the most logical order to help you manage potentially dozens of data sources and hundreds of data source requests.
Add Button Menu
This shows a menu allowing the creation of a new data source, folder or request beneath the currently selected tree node.
Data Source
You are permitted to have multiple ReST API's from numerous different servers. It is recommended therefore to give a name to each of these for example "Accounts API" or "Product Library" to easily differentiate where your data is sourced from. This will create a master tree node when you can then create sub-folders.
Folder
Create a folder beneath either a data source, or another folder. This allows you to structure your ReST API request hierarchy into logical groups.
Request
A data source request is a ReST API endpoint which is configured to consume data for CRUD operations using the supported HTTP methods. It is advisable to relate to the CRUD concept when naming your requests e.g. "Read a Product" or "Update a Product".
Each request is available to designers when designing forms, components and fields and these people may not be familiar with ReST API concepts, so naming requests descriptively is important.
Clone Button
This button is used to make a copy of the selected tree view item. You are prompted to rename the cloned item before it is created beneath the selected item.
Properties Panel
The properties panel shows properties of the selected tree node.
Insert Variable
This button is used to paste a selected custom variable into the data source request.
The popup dialogue has a drop down list of all custom variables. Selecting a variable will paste the variable into the request URL or Body.
The inserted variable will be shown with <# and #> field delimiters e.g.
Delete
The delete button is used to delete the currently selected data source, folder or request. It is a recursive operation i.e. removing a root node will also remove all children and children of children.
WARNING: Deleting requests may adversely impact the operations of your application so take great care.
Data Source Properties
When a data source is selected in the tree view, its properties are shown on the right.
There are two tabs displayed in the data source properties.
Details
These are the details of the data source.
ID
The read-only unique identifier of this data source. This is generated for each new data source and is only of importance to developers wishing to re-use this in their own applications.
Name
This is the name of the data source.
Description
A description about what this data source does.
Created
The date that this was created.
User
The user who created the data source.
Authorisation
These are the authorisation details associated with the data source.
Typically there are four types of authorisation associated with a data source. All children of a data source (folders and requests) can inherit authorisation from their parent. The values of each authorisation credential should be a server-side custom variable to allow centralised control.
None
Either the child data requests do not need authorisation, or the authorisation is configured per folder or per request.
Basic
A username and password is specified.
Bearer Token
A token is supplied.
API Keys
One or more key/value pairs are supplied at HTTP headers.
Folder Properties
When a folder is selected in the tree view, its properties are shown on the right.
Details
These are the details of the folder.
Authorisation
These are the authorisation details associated with the folder. The values of each authorisation credential should be a server-side custom variable to allow centralised control.
These are as follows:
Inherit from parent
Any authorisation credentials are inherited from the folder or data source above. This can be hierarchical so that the parents parent etc.. inherits the authorisation. This allows each set of ReST API requests to have their own centralised credentials.
None
Either the child data requests do not need authorisation, or the authorisation is configured per folder or per request.
Basic
A username and password is specified.
Bearer Token
A token is supplied.
API Keys
One or more key/value pairs are supplied as HTTP headers.
Request Properties
When a request is selected in the tree view, its properties are shown on the right.
This panel consists of the URL text box, a Send Request button, and several tabs.
URL
This uniform resource locator is the end-point of the ReST API. It should always start with https meaning that the end-point is secured with SSL.
This URL can contain parameters adhering to industry standards for example:
https://mydomain.com?product=switch&colour=white&material=plastic
In the example, the product parameter value is 'switch', the colour is 'white' and the material is 'plastic'.
It is most important when designing data source request URL's to use custom variables to define these parameters either on the URL itself, or using the Parameters tab.
This is an example of a URL used in the sample requests which deletes a nationality using a custom variable:
https://football-891b.restdb.io/views/DeleteNationality?ID=<#Nationality-ID#>The <#Nationality-ID#> custom variable was inserted into the URL using the Insert Variable button. It is strongly recommended to use this mechanism rather than trying to remember and type custom variable names.
Send Request
This button sends the ReST API request to the back-end and presents the data in the Results tab. IT also populates the fields in the Fields tab if they do not already exist.
Details
This tab has the usual properties plus the important HTTP Verb/Method.
The properties are as follows:
ID
The read-only unique identifier of this data source request. This is generated for each new data source request and is only of importance to developers wishing to re-use this in their own applications.
Description
A description about what this data source request does.
HTTP Verb
A drop down combo of all available HTTP methods.
Authorisation
This tab allows the authorisation credentials to be assigned for the ReST API data source request.
Inherit from parent
Any authorisation credentials are inherited from the folder or data source above. This can be hierarchical so that the parents parent etc.. inherits the authorisation. This allows each set of ReST API requests to have their own centralised credentials.
None
Either the child data requests do not need authorisation, or the authorisation is configured per folder or per request.
Basic
A username and password is specified.
Bearer Token
A token is supplied.
API Keys
One or more key/value pairs are supplied as HTTP headers.
Parameters
The parameters tab should be used when the ReST API end-point has multiple discretionary parameters i.e. one or more parameters can be used to filter the data set.
This is an example from the sample data where this end-point is used in a search component in which the end-user can provide zero or more filters:
The parameter format can be chosen from the drop-down Format field. Typically this will be of this form:
Argument per Parameter e.g. ?param1=value¶m2=value
This will add the parameters to the URL in this format.
The Add Parameter button opens a modal popup allowing the fields in the ReST API data source request to map to custom variables.
Each parameter added is shown in the list of fields beneath the button.
The Add Sort Parameter button opens a modal popup dialogue to select the format of the sort parameters and the name of the parameter.
These sort parameters are also appended to the URL instructing the ReST API to sort the data by a specific field. For example of the endpoint returns products, you may wish to sort these by product name, then category.
Headers
The headers tab is used where this specific data source request needs additional headers other than authorisation to control the data which is returned or updated.
The Add Header button adds a new row to the list. The key can be typed in and the value field should be inserted from the Insert Variable button. Header rows can be removed using the Delete button.
Body
The body tab is used for sending data from the application to the ReST API usually to create or update records.
The Body Format field provides two options:
JSON - JavaScript Object Notation
This is the recommended option as JSON is easy to read regardless of your technical expertise.
Grid - two dimensional table with columns and rows
Data is represented by rows and columns but without the clarity of JSON.
The values for each field should be inserted using the Insert Variable button as nothing should be hard-coded. The JSON body format shows a thumbnail of the body to the right which is useful when dozens of fields are being specified.
Results
This tab displays the results of the ReST API when the Send Request button is pressed.
The Results tab has 4 left docked sub-tabs.
The JSON sub-tab shows the raw JSON data received from the ReST API request. This may show field and data e.g.
{
"ID": "6863f56e78badf6500137ff3",
"Name": "Ana Crnogorčević",
"PhotoUrl": "https://xyz.restdb.io/media/12345-xyz-abc",
"PhotoID": "12345-xyz-abc-image",
"TeamName": "Cambridge United",The Fields sub-tab will show a list of fields returned from the ReST API request.
The Table sub-tab will show a table of data returned from the ReST API request.
The Grid sub-tab will show a data grid of the data returned from the ReST API request. This closely resembles how the data may look to the end-user when you hook this request up to forms.
Fields
This tab is where the fields received from the ReST API endpoint are listed when the Send Request button is invoked.
There are two panels in a master/detail configuration. Selecting a field in the Available Fields panel will show the field in the Field Properties panel.
The Available Fields panel lists all of the fields in the original order returned by the ReST API. These can be re-arranged by dragging and dropping fields using the left side drag icon. The right side delete button can be used to remove the field from the list. If the ReST API is under development and starts returning different fields, or indeed if you have deleted the wrong field, then the Refresh button refreshed the list of fields. Your specific field configuration will be lost in this instance though.
The field properties are as follows:
Name
The name of the column/field in the ReST API
Key
Whether this is a key field i.e. the product ID would uniquely identify a product, however a post code would not uniqiely identify an address.
Variable
This is a drop-down of all custom variables, one of which can be associated with this field.
Paging Attribute
This is a drop-down of four paging attributes used when this ReST API is paginated i.e. it returns a page of data at a time, rather than the entire, potentially very large data set: Page Number, Records per Page, Total Page Count, Total Record Count
Type
The type of field is often a string or a number, however all data types are supported including Image URL and Base64 which can show image data types.
Caption
This is the human readable text of the field when displayed in forms or grids.
Visible
Whether the field is visible in consuming forms or components.
Sample Values
A list of sample data values read from the ReST API
Last updated