Version tags

Access  ARCAD-API Server →  Embedded Production Server →  Production Package →  Version tags

Version tags are used to create versions of web service packages and therefore make them available to be consumed.

An important feature for production packages is the capability to manage the version of the set of web services. ARCAD-API offers the capability to define version tags that group multiple versions of web services that belong to the same production package under a unique version number. Even if each web service in the set is currently at a different version level, the final user will only have access to the versions included in the package's version tag. A version tag is a list of multiple web services (in the package) that each have different version levels themselves.

While creating a version tag for a category, ARCAD-API will include the latest version of all the web services that belong to the package.

Important!

Only tagged versions of production packages can be promoted to an external Kong server to delegate the management.

As soon as a version tag has been created and activated, the related API is available for the consumer. Web services are available at the following URL:

https://<arcad-api-server>:<arcad-api-port>/arcapi/exec/<package-code>/<version-tag-number>/<web-service-root-context>

Step 1   Open the Production Packages view and select the production package.

Step 2   Right-click on the package to display the contextual menu and select the Show Version Tags option.

Version tags are accessed and managed in the  Version Tags search view.

The version tags view

To refine the list of existing version tags displayed, use the Search tool.

  • To search for an existing version tags by number or description, enter all or part of the number or description in the corresponding field.

Enter any combination of the above search criteria, then click the Search button to display the results. To display the complete list, click the Search button without entering any search criteria.

To display all of the items by default each time the search view is opened, select the auto search icon.

Follow the subsequent steps to create a new version tag.

Step 1   To access the New Version Tags wizard, either click the  Create icon in the toolbar of the  Version Tags search view, or right-click anywhere in the view and select  Create.

Step 2   Define the version tag's Number and Description. These values are required to create a new tag but can be edited later.

Step 3    Click Finish.

Result   The new version tag is created and is displayed in the  Version Tags search view. Because the version tag is automatically associated with the parent production package, the most recent version of each promoted web service is automatically added to the version.

Once it is activated, the version will be able to be called by external consumers.

Reference

For more information about the URLs to use to access your APIs, refer to the Web services catalog.

To edit a version tag's details, either right-click on it in the  Version Tags search view then select Edit, select the item then click the edit icon in the toolbar or double-click it.

The Version Tag editor

Number
The version number.
Description
The short description of the version.
Active
Tick this checkbox to make the version tag available for consumption.
Important!

This option must be activated to make your web services available.

Comment
A detailed description of the version.
Tagged web services
The list of web services included in the version. The most recent version of each web service in the production package is automatically included in the version tag.

Save the changes (, Ctrl+S or File > Save).

 Kong is an Open Source API Gateway (konghq.com) that provides the following features:

  • Authentication
  • Traffic Control
  • Analytics
  • Transformations
  • Logging

ARCAD-API delegates API management to the external gateway Kong. In order to use your API, you must register it with Kong and set up the required elements. ARCAD-API enables you to register sets of APIs together via the version tag. Registering a tag with Kong will register all of the web services available in it and they will all become available via a single service.

Important!

ARCAD-API only registers a Kong Service and the required elements to make it work. The API management strategy belongs to the Kong Administrator so this means that you cannot create other management tools, like Route for example, from ARCAD-API.

Reference

To communicate with the Kong server, the HTTP request needs to use a Basic Authentication. This means that the Kong Server has to be aware of that authentication to be able to proxy the request to the ARCAD-API Server.

To manage this connection information, refer to Kong Gateway.

Follow the subsequent steps to register a service for each version of a production package.

Step 4   From the Version Tags search view, select the tag to register a service.

Step 5   Right-click on it to display the contextual menu and select Register in Kong.

Step 6   Once the registration is finished, the following data is returned by the Kong Admin API.

Kong Service List

Copy

GET http://<kong_server_address>:<admin_port>/services

{
    "next": null,
    "data": [
         {
             "host": "xxx.xxx.xx.x",                    <- The ARCAD-API Server IP Address or DNS
             "created_at": 1584625667,
             "connect_timeout": 60000,
             "id": "62b9a612-8089-47cb-b083-bd2140fdbf0e",
             "protocol": "http",
             "name": "TestPromoteV1",
             "read_timeout": 60000,                 
             "port": 6200,                                <- The ARCAD-API Server Port
             "path": "/arcapi/exec/.../V1",         <- The API Execution Path for the registered Version Tag
             "updated_at": 1584625667,
             "retries": 5,
             "write_timeout": 60000,
             "tags": null,
             "client_certificate": null
         }
     ]
 }
Note

The protocol, host and port attributes are extracted from the Base URL defined in the server configuration. See: Kong Gateway

The path attribute is the root URI used to execute a web service exposed in the related version tag.

The name attribute is assigned using the concatenation of the parent production package code and the version number of the version tag.

Service Plugin registration

Copy

GET http://<kong_server_address>:<admin_port>/services/<version>/plugins

{
    "next": null,
    "data": [
        {
            "created_at": 1584625667,
            "config": {
                "remove": {
                    "querystring": [],
                    "headers": [],
                    "body": []
                },
                "replace": {
                    "querystring": [],
                    "headers": [],
                    "uri": null,
                    "body": []
                },
                "http_method": null,
                "add": {
                    "querystring": [],
                    "headers": [
                        "Authorization: Basic YWRtaW5AcXVhZHJhOnF1YWRyYQ=="  <- The Authorization key
                    ],
                    "body": []
                },
                "append": {
                    "querystring": [],
                    "headers": [],
                    "body": []
                },
                "rename": {
                    "querystring": [],
                    "headers": [],
                    "body": []
                }
            },
            "id": "445f7a06-8d6a-459e-b289-89ea6ade1f08",
            "service": {
                "id": "62b9a612-8089-47cb-b083-bd2140fdbf0e"
            },
            "enabled": true,
            "protocols": [
                "grpc",
                "grpcs",
                "http",
                "https"
            ],
            "name": "request-transformer",  <- The request-transformer plugin installed
            "consumer": null,
            "route": null,
            "tags": null
        }
    ]
}
Note

The data/config/add/headers[0] is an header that defines the Basic Authentication String used by Kong to connect to the ARCAD-API Server to execute the REST API.

This connection string is built using the ARCAD-API user defined in the server configuration. See: Kong Gateway.

ARCAD-API delegates API management to the external gateway  APIGEE Edge. In order to use your API, you must register it with APIGEE and set up the required elements. ARCAD-API enables you to register sets of APIs together via the version tag. Registering a tag with APIGEE will register all of the web services available in it and they will all become available via a single service. You can also deploy the web-services tagged to APIGEE Edge just after registering.

The registration process is the following one:

  • Copy and unzip the selected template zip file.
  • For each web service that belongs to the selected version tag:
    • Substitute the variables in to template xml file.
    • Zip the modified directory.
    • Call the related APIGEE Rest API to create a KVM that will contains the ARCAD-API Credentials.
    • Call the related APIGEE Rest API to register the new API Proxy.
    • If registration is OK, retrieve the revision number.
    • If the Deploy after registering option has been checked, all the related APIGEE Rest API to deploy the newly revision into the selected target environment.

Follow the subsequent steps to register a version tag to an APIGEE API Proxy.

Step 1   Select the version tag you want to register, click the  Register icon in the toolbar of the  Version Tags search view, or right-click on the Version Tag in the view and select  Register.

Step 2    In the APIGEE API Proxies Registration wizard, select the APIGEE Registration Template you want to use in the drop-down list.

Step 3   [Optional] Check the Deploy after registering box.

If you select the Deploy after registering option, the web-services tagged to the selected version are deployed on the selected Target Environment once the registration is completed.

Step 4   Select the APIGEE Environment to deploy to in the Target Environment drop-down list.

Step 5    Click Finish.

Result   The registration is done.

Generate a documentation for the web services compliant to the , Open API specification. You can choose to use the Swagger 2.0 version or the Open API 3.0 version of the standard.

Reference

For more information about Open API standard, refer to:

https://spec.openapis.org/oas/v3.1.0 or https://swagger.io/resources/open-api/

Exporting a descriptor will create a compressed file that contains all of the elements required to describe the web service according to the Open API specification.

Follow the subsequent steps to export a web service specification to the open API standard.

Step 1   Right-click on a version tag in the list and select  Export Specification or select the version tag and click the Export Specification icon.

Step 2   Define the specification version: select 2.0 to use Swagger 2.0 or 3.0 to use Open API 3.0 in the Open API Version drop-down list.

Step 3   Select the web services you wish to export. Click to select the web service in the list, or tick the Select All box to include all web services of the package's version.

Step 4   Browse to select the desired location in which to save the file in the Save As dialog and enter a name for the exported file.

Step 5   Click the Save button to export.

Result   The Open API web service specification is exported to the JSON format.

Use the following web service URL for displaying the documentation:

http://<server>:<port>/arcapi/export/specification/<specVersion>/<packageCode>/<package_version>/<webServiceDescriptorCode>