JSON Sources

To create a new JSON data source, right-click on the Server Explorer and click New > Data source > JSON.

The Tool will display the dialog to create the data source.

Creating a JSON data source

Creating a JSON data source

The following data are requested in this dialog:

  • Name. Name of the new data source.

  • Endpoint access configuration. There are two options to configure the access to the data:

    • Direct. You enter the path to the JSON file that contains the data.

    • From OpenAPI 3 document. You configure the connection details to an OpenAPI 3 document where the operations of a service are defined. The base views will be created from them.

  • Ignore route errors. If selected, the Server will ignore the errors occurred when accessing the file(s) to which the data source points.

    This option is not meant to be used when the data source reads a single file. Its main purpose is when the data source points to a collection of files and you know some of them may be missing. For example, you can create a JSON data source to read a set of log files with this local path: /opt/application/logs/log-^DateRange("yyyy/MM/dd",@start_date,@end_date,"yyyy-MM-dd").json (see more about the function “DateRange” in the section Paths Using Date Ranges).

    When you query a base view created over this data source, the data source will read all the log files in order. For example, if in the query you put the condition start_date='2018/05/01' AND end_date = '2018/05/04', the data source will try to read the files “log_2018-05-01.json”, “log_2018-05-02.json”, “log_2018-05-03.json” and “log_2018-05-04.json”. If one these files is missing, the query will fail.

    If you want to ignore this error, select the check box Ignore route errors. With this option if one of the files does not exist or cannot be read, the data source will skip it and read the next one. If you run the query from the administration tool, you can identify which files could not be read in the Execution trace. In the trace, click on the nodes with Type = Route. The ones that could not be read will have the attribute Exception followed by an error message.

In the Metadata tab, you can set the folder where the data source will be stored and provide a description.

When editing the data source, you can also change its owner by clicking the button image1.

Click Save to create the data source.

Direct

When you use Direct configuration you have to configure the Data route. This is the path to the JSON file that contains the data. This path can be parameterized according to the query made using interpolation variables (see section Paths and Other Values with Interpolation Variables). The section Path Types in Virtual DataPort describes the formats of the available paths and how to use parameters in them. The most common path type in this case is HTTP client.

After creating the data source, click Create base view to begin creating the base view. If the path type selected is HTTP client, the Tool will open the “Configure JSON base view” dialog where you can configure a relative route for the base view you want to create.

Configuring JSON base view

Configuring JSON base view

This dialog shows the following fields:

  • Configuration.

    • HTTP Method. HTTP method that the base view will execute.

    • Base URL. Data source’s URL (for example: http://www.library.com/). This field cannot be modified.

    • Relative URL. Base view’s relative URL (for example: “/books”), this URL will be concatenated to the Base URL when executing the base view (the resulting URL will be http://www.library.com/books).

    • HTTP headers. Base view’s URL headers, they will be applied to the URL when executing the base view.

  • Pagination. Pagination settings for the base view URL.

  • Filters. Filter settings for the base view URL.

This way, a data source that defines a base URL (http://www.library.com/) can be reused to create a base view with its own relative URL for each resource we want to access (“/books”, “/authors”, “/bookById/{id}”, etc).

After configuring the base view route and clicking Ok, the “Configure JSON Wrapper” dialog will appear. If the selected path type is other than HTTP client, the “Configure JSON Wrapper” dialog will appear immediately after clicking “Create base view” and the previously explained dialog (“Configure JSON base view”) will not be displayed.

With the “Configure JSON Wrapper” dialog you can change the “tuple root” of the base view if you only want to access a portion of the JSON document. We recommend leaving the JSON root check box selected and click Ok.

Creating a JSON base view

Creating a JSON base view

If the path to the data file includes interpolation variables, there is an intermediate step where you have to provide a value for these variables. See section Paths and Other Values with Interpolation Variables.

After this, the Tool will display the schema of the new base view. At this stage, you can do the following:

  • Change the name of the view.

  • Change the name of each field by double-clicking it and its type, by using the drop-down list to the right.

  • Set the primary key of the new view (see the section Primary Keys of Views).

  • In the Metadata tab, you can set the folder where the base view will be stored and provide a description.

  • When editing the base view, you can also change its owner by clicking the button image1.

After this, click Save (image3) to create the base view.

In the Server Explorer, double-click the new base view to display its schema (see section Creating Derived Views). Click Edit to modify the base view.

From OpenAPI 3 document

This option is to create the base views from an OpenAPI 3 document. You have to configure the route to the document. It can be a Local file or be accesible in a HTTP server (with HTTP basic or digest authentication).

Once the access to the OpenAPI 3 document has been specified, the following parameters can be configured: “Configuration”, “Pagination”, “Proxy”, “Authentication” and “Filters”. The base views that are created on this Open API data source, will use by default the values of this configuration when they are executed.

Creating an Open API data source

Creating an Open API data source

By clicking on the “Load default values from OpenAPI3 Specification” button, the Base URL field of the “Configuration” tab will be automatically filled with the URL specified in the OpenAPI 3 document. This Base URL will be the address to which the endpoints of the OpenAPI specification operations will be concatenated.

For example, if the API server defined in the document is https://www.library.com/ this will be the base URL. Then, if a base view is created for an operation with the “/books” endpoint, when this view is executed the endpoint will be concatenated to the base URL (obtaining the address https://www.library.com/books) and the configuration (authentication, paging, proxy, etc) defined in the data source will be used.

For more information about the Open API data sources you can see OpenAPI 3 Data Sources FAQ.