RESTful API Services (Magic xpi 4.14)
RESTful API services contain the following parameter. The parameters in bold are mandatory.
|
|
|
|
Server URL
|
Server URL is also known as base path which will be used to define the API endpoint. The server URL and the Path will create one API endpoint URL that can be invoked for HTTP operations like Get, Post etc.
This URL is for display purpose only and does not have any runtime implication.
When the OpenAPI specification is used, the Server URL will be populated from the OpenAPI specifications file. If the Server URL is not provided it will take the default URL as http://localhost:6443/xpiREST.
|
|
The Server URL should not start with or end with the dot (.) and slash (/) characters. Apart from this, the characters which are not allowed to be used as a part of Server URL are [space] < > { } | \ ^~ #
|
|
|
API Definition Method
|
Select one of the two API Definition methods below:
To configure the service with OpenAPI Specification file, select the method as OpenAPI. Once selected you can select the file using the Load OpenAPI button.
|
|
OpenAPI Document
|
This is the path of the OpenAPI Document imported using the Load OpenAPI button.
|
|
OpenAPI Document Version
|
This field will be populated once the Open API file is loaded using the Load OpenAPI button. Magic xpi supports 2.x and 3.0.x version of Open API.
|
|
OpenAPI version 3.1 is not supported
|
|
|
Security
|
This is a combo-box. Select the required security type from the drop-down list.
|
|
If Security is selected as Basic, an additional Request parameter UserId will be added. This parameter value will be the User Id you have configured as part of Basic authentication. You can map this parameter to Alpha type of variable and use it in the flow logic.
|
|
RESTful API services also give you the following buttons:
|
|
|
|
Paths
|
Path is generally the route through which the user can access the REST API. The value of the Path parameter will be appended to the Server URL in order to form REST API endpoint. The Path is URL path and when combined with HTTP verb like Get or Post etc., it becomes one unit for one API call.
Click on the Paths button to define the Paths to invoke the RESTful service in xpi. On the Paths window the user can add or remove the Query Parameters, Header Parameters, Form Parameters for each path.. For more information, click here.
When the API Definition method is selected as Open API, then the paths will be auto populated using the Open API document.
In this case the paths will be non-editable. Any change to the path needs to be done in the Open API document and then imported again. In custom mode users can enter their own paths.
On switching the method to custom from OpenAPI, all the paths populated using the OpenAPI Specification will be retained and users can manually edit them.
|
|
Load OpenAPI
|
To open the API specification file, click on the Load OpenAPI button. This will provide a file dialog where you can choose the API specification file of either YAML or JSON type. Once the file is selected, the xpi will read the file and populate the OpenApi Document Version and the OpenApi Document path above.
|
|
Generate Flows
|
This button will generate the template flows for the paths defined on this service. A RESTful trigger will be added to each of these flows. The trigger will implement the path and add all the request, query, header and cookie parameters for this path. A flow variable will be generated for each of these parameters. Similarly flow variables will be created for Response body, Response header and Response status and assigned to the trigger. User can then implement their business logic in each flow.
|
|
|
When creating the copy of the xpi project using the "Save Copy As" menu of Studio, the serviceDefinition.xml files of the RESTful services are not updated with the new project name. You need to manually update the file names to include the updated project name so as to maintain the uniqueness. Also, open the file in a text editor and update the project name in the "project" attribute of the root "service" element in the XML file.
|
Once the service is saved the serviceDefinition file will be generated under the <xpi project>/RESTful API\<ServiceNameFolder>\ folder in the format <Projectname>_<Servicename>_serviceDefinition.xml
This file has to be copied to the rest-services folder of the Web Server. For further details, refer to the Magic xpi - RESTful API Provider Installation Instructions.pdf available under the Help folder in the xpi installation.
If the Open API specification contains schema, then the corresponding JSON Schema files will be generated under "<xpi project>\RESTful API\<ServiceNameFolder\OpenApiSchema\" folder.
You can use these schemas in the Data Mapper steps for further processing.
Since version: 4.14
