Project

General

Profile

Manual submission of a datasource in the Data Mashup Editor

Once reached the Datasource registration page, as described in the wiki Register a datasource in the Data Mashup Editor, the user can manually register a datasource into the Data Mashup Editor. To do so it's necessary to select the tab Create Datasource (it should be selected by default).

The other two tabs are reserved for importing the datasource specification from the Digital Enabler's Data Workspace or from an external descriptor, then we will ignore them in this guide.
Then, below there is the section Datasource Info that allows to specify a Title and a description of the datasource itself. The user here can write whatever he thinks maybe helpful in identifying the datasource.

In this example we put the following values:

Going below the user can add several resources related to the current datasource.
Each resource can be documented with the information about the endpoint, the parameters and the possible responses. Each of these information can be provided in the corresponding tab.

1. Populating the resource endpoint

Here the required fields are:
  • a title
  • the complete URL of the resource
  • the HTTP Method to be used for invoking the endpoint

The title and the description can be the ones the user thinks can be the most meaningful.

The URL section must contain the entire URL to be invoked. So, acceptable values are:

Relative paths, like_ /myresource _are, instead, not allowed!

Once the datasource is saved, every query parameter provided in the URL will be automatically moved to the parameters section. The provided values will be considered as default values

In case the resource doesn't require any further parameter, please move to the "Finalize the resource" paragraph.


Example

Let's image we want to register an API that can be invoked as follows:

curl -X POST 'https://mydatasource.com/myresources?attrs=uuid&format=true' -H 'Content-Type: application/json' -H 'auth-token: xyz' -d '{ "first": "one", "second": "two" }'

The URL to put in the Endpoint tab is https://mydatasource.com/myresources


2. Specify the resource parameters

In the parameters tab the user can document all the input parameters of the resource.

When opened, the parameters tab shows an empty list of parameters.
This list can be populated through the underneath New Parameter form. In this form the user can:
  • specify the name of the parameter
  • put (optionally) an explanatory description of the parameter
  • specify the type of the parameter. The allowed types are:
    • String
    • Number
    • Boolean
    • JSON Object
    • JSON Array
  • specify (optionally) a default value for the parameter
  • specify the style of the parameter, i.e. the position that parameter will have in the request.
    • Query
    • Path
    • Header
    • Body (only 1 body allowed)

All the parameter names (but the body one) will be used to build the HTTP request. So be sure to fill them in with the exact values the actual endpoint expects.

Remember that the Content-Type header must be provided only if it's not application/json otherwise it must be skipped.

Please note that each Path parameter must have a placeholder in the URL. The placeholder is built wrapping up the parameter name between curly braces. The upcoming example will be explanatory...


Example

In order to document all the input parameters of the following API:

curl -X POST 'https://mydatasource.com/myresources/3?attrs=uuid&format=true' -H 'Content-Type: application/json' -H 'auth-token: xyz' -d '{ "first": "one", "second": "two" }'

We have to specify the endpoint as follows:

https://mydatasource.com/myresources/{resourceid}

and put the following parameters:

  • name: resourceid
    • type: String
    • style: Path
  • name: attrs
    • type: String
    • style: Query
  • name: format
    • type: Boolean
    • style: Query
  • name: auth-token
    • type: String
    • style: Header
  • name: Payload (or whatever the user wants.. this is only a placeholder)
    • type: JSON Object
    • style: Body

Eveytime a paramter is fully documented it can be added to the resource by clicking the button.

3. Document the responses

The documentation of the responses is not mandatory. It's just for documentation purposes.

Every Response the user wants to document must have at least a Status code and a JSON Schema.
Optionally the user can write also a brief Description of the Response.

In case the JSON Schema is unknown, or the response is not a JSON, the user can simply write an empty schema {}.

For each documented response don't forget to click the button.

4. Finalize the resource

When the resource is documented as the user expects, it's possible to add it to the datasource by clicking on the button.

All the section are cleaned-up and a summary of the just submitted resource will be available in the resource list of the datasource

Now the user can repeat the steps from 1 to 4 of this guide for each resource he wants to add to the datasource. When all the resources have been registered, click on the button to finalize the datasource creation.

The datasource and all of its resources can be anytime modified. So don't worry if you missed or mistyped something. You can always come back to fix it as described in the Edit a Data Mashup Editor datasource guide.