This documentation is for WSO2 Governance Registry 5.1.0. View documentation for the latest release.
||
Skip to end of metadata
Go to start of metadata

WSO2 Governance Registry (G-Reg) is a registry-repository for storing and managing metadata related to services and other artifacts. WSO2 API Manager (APIM) is used to create, edit, and manage APIs. The APIM consists of 4 main components as follows:

  • API Publisher: A Web interface for API creators to develop, document, scale and version APIs, while also facilitating more API management-related tasks such as publishing API, monetization, analyzing statistics, and promoting.
  • API Store: A collaborative Web interface for API publishers to host and advertise their APIs, and for API consumers to self register,discover, evaluate, subscribe to and use secured, protected, authenticated APIs.
  • API GatewayA runtime backend component (an API proxy) developed using WSO2 ESB for securing, protecting, mediating, and scaling API calls.
  • Key Manager: A server for managing all client, security, and access token-related operations. The API Gateway connects with the Key Manager to check the validity of OAuth tokens, subscriptions and API invocations.

In this guide, we explain how to install the API Publisher and Store as features in the G-Reg, instead of having a separate APIM server to perform API management.  Alternatively, you can  integrate an  external  APIM server   with the G-Reg as explained in  Integrating with an External WSO2 API Manager .

Deployment

The following diagram depicts how the databases are shared among the APIM and G-Reg nodes.

minimal setup of the integration

Prerequisites

Follow the steps below to set up the required prerequisites before starting the integration.

Deploying the WSO2 products

Follow the steps below to deploy WSO2 APIM and WSO2 G-Reg.

  1. Download WSO2 API Manager (1.9.x versions).
  2. Download WSO2 Governance Registry (version 5.0.0 or above).
  3. Change the default port of the APIM by applying an offset of 1 in the <APIM_HOME>/repository/conf/carbon.xml file. This avoids port conflicts that may arise when running more than one WSO2 products on the same server.
  4. Start the APIM. It acts as both the API Gateway and Key Manager in this guide.
    • On Windows<APIM_HOME>\bin\wso2server.bat --run
    • On Linux/Solaris/Mac OSsh <APIM_HOME>/bin/wso2server.sh

  5. Start the G-Reg server. It acts as both the G-Reg Publisher and G-Reg Store in this guide.
    • On Windows<G-REG_HOME>\bin\wso2server.bat --run
    • On Linux/Solaris/Mac OSsh <GREG_HOME>/bin/wso2server.sh

Setting up the databases

Follow the steps below to create the databases to store APIM and G-Reg-related and user management-related data. These databases are shared across the servers.

  1. Execute the following commands to create three local MySQL databases named apimgtdbregdb and userdb.
    • CREATE DATABASE apimgtdb;
    • CREATE DATABASE userdb;
    • CREATE DATABASE regdb;
  2. Execute the following database scripts to create tables in the corresponding database as follows. 
    • Execute the  <APIM_HOME>/dbscripts/apimgt/mysql.sql script against the apimgtdb database.
    • Execute the  <G-REG_HOME>/dbscripts/mysql.sql  script against the userdb database.

    • Execute the  <G-REG_HOME>/dbscripts/mysql.sql  script against the regdb database.
  3. Download the mysql-connector, and add it to the <G-REG_HOME>/repository/component/lib/ directory of all product distributions.

Configuring WSO2 G-Reg 

Follow the steps below to configure the G-Reg instance.

  1. Log in to the Management Console of the G-Reg server using the following URL and admin/admin credentials:  https://localhost:9443/carbon.

  2. Click Configure, and then click Features.

  3. Click Add Repository, add the URL of the hosted APIM P2 repository, and click  Add. For more information, go to  Provisioning WSO2 Carbon based SOA Products with Equinox P2.

    add APIM feature repo

  4. Click Find Features.
  5. Click API Publisher to expand it, and select  API Publisher 2.0.1.
  6. Click API Publisher 2.0.1 to expand it, and deselect the following features as shown below.
    • Carbon 4.4.4
    • Carbon 4.4.3
    • Carbon 4.4.2
    • Carbon Common 4.4.4
    • Carbon Common 4.4.3
    • Carbon Common 4.4.2
    • Carbon Runtime 4.4.4
    • Carbon Runtime 4.4.3
    • Carbon Runtime 4.4.2
    • Carbon Server 4.4.4
    • Carbon Server 4.4.3
    • Carbon Server 4.4.2
    • Carbon UI 4.4.4
    • Carbon UI 4.4.3
    • Carbon UI 4.4.2
    • Registry Content Search 4.5.2
    • Registry Core 4.5.2
    • Registry Core Server 4.5.2
    • Registry Core Server 4.5.0
    • Registry Resource Properties 4.5.2
    • Registry UI Menu 4.5.2
  7. Click API Store to expand it, and select API Store 2.0.1.
  8. Click  API Store 2.0.1  to expand it, and deselect the following features as shown below as shown below. 
    • Carbon 4.4.4
    • Carbon 4.4.3
    • Carbon 4.4.2
    • Carbon Common 4.4.4
    • Carbon Common 4.4.3
    • Carbon Common 4.4.2
    • Carbon Runtime 4.4.4
    • Carbon Runtime 4.4.3
    • Carbon Runtime 4.4.2
    • Carbon Server 4.4.4
    • Carbon Server 4.4.3
    • Carbon Server 4.4.2
    • Carbon UI 4.4.4
    • Carbon UI 4.4.3
    • Carbon UI 4.4.2
    • Registry Community Features Server 4.5.0
    • Registry Content Search 4.5.2
    • Registry Core 4.5.2
    • Registry Core Server 4.5.2
    • Registry Core Server 4.5.0
    • Registry Resource Properties 4.5.2
    • Registry UI Menu 4.5.2
  9. Click Install.
  10. Click Next> to continue installing these feature categories until the feature installation is successful as shown below. 
    click Next
  11. Select  I accept the terms of the license agreement, and then click Next> again to accept the license agreement. 
  12. Click Restart Later to opt to restart later once the feature installation is successfully done.
  13. Press Ctrl+C keys in the Command Prompt in which you ran the G-Reg server to stop it. 
  14. Navigate to the <G-REG_HOME>/repository/conf/api-manager.xml file, and change the configurations as follows:
    1. Enter the Key Manager servlet transport URL for the value of the <ServerURL>  element in the <APIKeyValidator> section as follows: <ServerURL>https://localhost:9444/services/</ServerURL>.
    2. Change the value of the <EnableThriftServer> element to false to disable the Thrift server start up as follows:  <EnableThriftServer>false</EnableThriftServer>
    3. Enter the gateway servlet transport URL for the value of the <ServerURL>  element i n the <APIGateway> section as follows: <ServerURL>https://localhost:9444/services/</ServerURL>.
    4. Enter the APIM Gateway pass-thru transport URLs as the value of the In the <GatewayEndpoint>  element in the  <APIGateway> section as follows:<GatewayEndpoint>http://localhost:8281,https://localhost:8244</GatewayEndpoint>
    5. Enter the gateway pass-thru HTTPS URL as the value of the <RevokeAPIURL> element as follows: <RevokeAPIURL>  https://localhost:8244/revoke   </RevokeAPIURL>.
  15. In the <G-REG_HOME>/repository/conf/datasources/master-datasources.xml file, remove the existing WSO2AM_DB datasource configuration and add the configuration below. Change the values of the <username> and <password> elements to point to the APIM DB (i.e. the apimgtdb database) created above:

    <datasource>
    <name>WSO2AM_DB</name>
    <description>The datasource used for the API Manager database</description>
    <jndiConfig>
      <name>jdbc/WSO2AM_DB</name>
    </jndiConfig>
    <definition type="RDBMS">
      <configuration>
        <url>jdbc:mysql://localhost:3306/apimgtdb?autoReconnect=true</url>
        <username>user</username>
        <password>password</password>
        <defaultAutoCommit>false</defaultAutoCommit>
        <driverClassName>com.mysql.jdbc.Driver</driverClassName>
        <maxActive>50</maxActive>
        <maxWait>60000</maxWait>
        <testOnBorrow>true</testOnBorrow>
        <validationQuery>SELECT 1</validationQuery>
        <validationInterval>30000</validationInterval>
      </configuration>
    </definition>
    </datasource>
  16. Add the following configurations to the <G-REG_HOME>/repository/conf/datasources/master-datasources.xml  file to add new datasources for the newly created userdb and regdb databases. 

    <datasource>
    <name>WSO2UM_DB</name>
    <description>The datasource used by user manager</description>
    <jndiConfig>
      <name>jdbc/WSO2UM_DB</name>
    </jndiConfig>
    <definition type="RDBMS">
      <configuration>
        <url>jdbc:mysql://localhost:3306/userdb?autoReconnect=true</url>
        <username>user</username>
        <password>password</password>
        <driverClassName>com.mysql.jdbc.Driver</driverClassName>
        <maxActive>50</maxActive>
        <maxWait>60000</maxWait>
        <testOnBorrow>true</testOnBorrow>
        <validationQuery>SELECT 1</validationQuery>
        <validationInterval>30000</validationInterval>
      </configuration>
    </definition>
    </datasource>
    <datasource>
    <name>WSO2RegDB</name>
    <description>The datasource used by user manager</description>
    <jndiConfig>
      <name>jdbc/WSO2REGDB</name>
    </jndiConfig>
    <definition type="RDBMS">
      <configuration>
        <url>jdbc:mysql://localhost:3306/regdb?autoReconnect=true</url>
        <username>user</username>
        <password>password</password>
        <driverClassName>com.mysql.jdbc.Driver</driverClassName>
        <maxActive>50</maxActive>
        <maxWait>60000</maxWait>
        <testOnBorrow>true</testOnBorrow>
        <validationQuery>SELECT 1</validationQuery>
        <validationInterval>30000</validationInterval>
      </configuration>
    </definition>
    </datasource>
  17. Change the value of the dataSource  property of the  <UserManager>  element in the <GREG_HOME>/repository/conf/user-mgt.xml file as follows.

    <configuration> 
        <Property name="dataSource">jdbc/WSO2UM_DB</Property>
    </configuration>
  18. In the <GREG_HOME>/repository/conf/registry.xml file, add the newly created regdb database-specific datasource configuration and the registry mounting configuration after the <dbConfig name="wso2registry"> element as follows:

    <dbConfig name="govregistry">
      <dataSource>jdbc/WSO2REGDB</dataSource>
    </dbConfig>
    <remoteInstance url="https://localhost:9443"> 
       <id>gov</id>
       <cacheId>root@jdbc:mysql://localhost:3306/regdb</cacheId> 
       <dbConfig>govregistry</dbConfig>
       <readOnly>false</readOnly>
       <enableCache>true</enableCache>
       <registryRoot>/</registryRoot>
    </remoteInstance>
    <mount path="/_system/governance" overwrite="true">
       <instanceId>gov</instanceId>
       <targetPath>/_system/governance</targetPath>
    </mount>
    <mount path="/_system/config" overwrite="true">
       <instanceId>gov</instanceId>
       <targetPath>/_system/config</targetPath>
    </mount>
  19. Restart the G-Reg Publisher server instance with the -Dsetup attribute.
  20. Log in to the management console using admin/admin credentials and the following URL: https://<G-REG_HOST>:<G-REG_PORT>/carbon
  21. Click Extensions, click Artifact Types in the Configure menu, and then click api.
  22. Change the value of the required property to false, of the Context Template and Version Type attributes by editing the api.rxt file of the artifact from the provided editor, and click Save.

Configuring WSO2 APIM 

Follow the steps below to configure the APIM server instance.

  1. In the <APIM_HOME>/repository/conf/api-manager.xml file, go to the <APIKeyValidator> section and change the value of the  <KeyValidatorClientType> element to WSClient and set the <EnableThriftServer> element to false
    <KeyValidatorClientType>WSClient</KeyValidatorClientType>
    <EnableThriftServer>false</EnableThriftServer> 
  2. In the  <APIM_HOME>/repository/conf/datasources/master-datasources.xml file, remove the existing WSO2AM_DB datasource configuration and add the configuration below. Change the values of the  <username> and <password>  elements to point to the APIM DB (i.e., the apimgtdb database) created above:

    <datasource>
     <name>WSO2AM_DB</name>
     <description>The datasource used for the API Manager database</description>
     <jndiConfig>
       <name>jdbc/WSO2AM_DB</name>
     </jndiConfig>
     <definition type="RDBMS">
       <configuration>
         <url>jdbc:mysql://localhost:3306/apimgtdb?autoReconnect=true</url>
         <username>user</username>
         <password>password</password>
         <defaultAutoCommit>false</defaultAutoCommit>
         <driverClassName>com.mysql.jdbc.Driver</driverClassName>
         <maxActive>50</maxActive>
         <maxWait>60000</maxWait>
         <testOnBorrow>true</testOnBorrow>
         <validationQuery>SELECT 1</validationQuery>
         <validationInterval>30000</validationInterval>
       </configuration>
     </definition>
    </datasource>
  3. In the same file, define new datasources for the newly created userdb and regdb as follows. Change the values of the  <username> and  <password> elements to point to the databases you created above:

    <datasource>
     <name>WSO2UM_DB</name>
     <description>The datasource used by user manager</description>
     <jndiConfig>
       <name>jdbc/WSO2UM_DB</name>
     </jndiConfig>
     <definition type="RDBMS">
       <configuration>
         <url>jdbc:mysql://localhost:3306/userdb?autoReconnect=true</url>
         <username>user</username>
         <password>password</password>
         <driverClassName>com.mysql.jdbc.Driver</driverClassName>
         <maxActive>50</maxActive>
         <maxWait>60000</maxWait>
         <testOnBorrow>true</testOnBorrow>
         <validationQuery>SELECT 1</validationQuery>
         <validationInterval>30000</validationInterval>
       </configuration>
     </definition>
    </datasource>
     
    <datasource>
     <name>WSO2RegDB</name>
     <description>The datasource used by user manager</description>
     <jndiConfig>
       <name>jdbc/WSO2REGDB</name>
     </jndiConfig>
     <definition type="RDBMS">
       <configuration>
         <url>jdbc:mysql://localhost:3306/regdb?autoReconnect=true</url>
         <username>user</username>
         <password>password</password>
         <driverClassName>com.mysql.jdbc.Driver</driverClassName>
         <maxActive>50</maxActive>
         <maxWait>60000</maxWait>
         <testOnBorrow>true</testOnBorrow>
         <validationQuery>SELECT 1</validationQuery>
         <validationInterval>30000</validationInterval>
       </configuration>
     </definition>
    </datasource>
  4. In the <APIM_HOME>/repository/conf/user-mgt.xml file, change the value of the dataSource property of the <UserManager> element as follows.

    <configuration> 
        <Property name="dataSource">jdbc/WSO2UM_DB</Property>
    </configuration>
  5. In the <APIM_HOME>/repository/conf/registry.xml file, add the newly created regdb database-specific datasource configuration and the registry mounting configuration after the <dbConfig name="wso2registry"> element as follows:

    <dbConfig name="govregistry">
      <dataSource>jdbc/WSO2REGDB</dataSource>
    </dbConfig>
    <remoteInstance url="https://localhost:9443"> 
       <id>gov</id>
       <cacheId>root@jdbc:mysql://localhost:3306/regdb</cacheId> 
       <dbConfig>govregistry</dbConfig>
       <readOnly>false</readOnly>
       <enableCache>true</enableCache>
       <registryRoot>/</registryRoot>
    </remoteInstance>
    <mount path="/_system/governance" overwrite="true">
       <instanceId>gov</instanceId>
       <targetPath>/_system/governance</targetPath>
    </mount>
    <mount path="/_system/config" overwrite="true">
       <instanceId>gov</instanceId>
       <targetPath>/_system/config</targetPath>
    </mount>
  6. Change the endpoint URL in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_AuthorizeAPI_.xml file as follows to point to the API Key Manager.

    _AuthorizeAPI.xml
    <endpoint>
      <http uri-template="https://localhost:9444/oauth2/authorize">
      </http>
    </endpoint>
  7. Change the endpoint URL in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_RevokeAPI_.xml file as follows to point to the API Key Manager.

    _RevokeAPI.xml
    <endpoint>
      <http uri-template="https://localhost:9444/oauth2/revoke">
      </http>
    </endpoint>
  8. Change the endpoint URL in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_.xml file as follows to point to the API Key Manager.

    _TokenAPI.xml
    <endpoint>
      <http uri-template="https://localhost:9444/oauth2/token">
        <timeout>
           <duration>60000</duration>
           <responseAction>fault</responseAction>
        </timeout>
      </http>
    </endpoint>
  9. Press Ctrl+C keys in the Command Prompt in which you ran the APIM server to stop it. 
  10. Restart the APIM Key Manager server instance with the  -Dsetup  attribute.

Follow the steps below to overcome the host name verification failed issue if you face it, by turning off the host name verification of the APIM Gateway and APIM Key Manager.

  1. Uncomment the HostnameVerifier parameter in the <transportSender name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender"> section of the <APIM_HOME>/ repository/conf/axis2/axis2.xml file of both APIM Gateway and APIM Key Manager servers.
  2. Enter AllowAll as the value of the HostnameVerifier parameter as follows.

    <transportSender name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLSender">
    <parameter name="HostnameVerifier">AllowAll</parameter>
    </transportSender>

Testing the integration

You can test the integration by creating a new API and invoking it, or by publishing a SOAP/REST service (an existing service or one which you create) and invoking it as demonstrated below.

By creating a new API 

Follow the steps below to create an API in the G-Reg Publisher node, and view it using the G-Reg Store.

  1. Log in to the G-Reg Publisher using the following URL and admin/admin credentials:  https://10.100.5.72:9443/publisher
  2. Click Add button of APIs in the Other Assets section as shown below.
    add a new API
  3. Select Design new API as shown below.
    design new API
  4. Click Start Creating.
  5. Enter the name, context and the version as shown below.
    design API
  6. Click Next: Implement>.
  7. Click OK in the message which pops up as shown below.
    popup message to specify a wildcard resource
  8. Click Managed API as shown below.
    click Managed API
  9. Enter a preferred backend endpoint for Production Endpoint as shown in the example below.
    add production backend endpoint
  10. Click Manage.
  11. Select Unlimited for Tier Availability as shown below.
    select tier
  12. Click Save & Publish.
  13. Click Go To API Store in the message which pops up as shown below.
    go to API Store
  14. Click the  Sign in  button in the top right corner, and sign in using admin/admin credentials. You view the created API in the G-Reg Store.

  15. Click on the published API to get the following screen.
    created APISelect Default Application for Applications as shown below.
    select default application
  16. Click Subscribe.
  17. Click Go To My Subscriptions in the message which pops up.
    goto my subscriptions pop up message
  18. Click Generate Keys under the KEYS - PRODUCTION section. You view the token you generate as shown below. 

    You can skip this step if you already did it before.


    generated token

  19. Click the following My Subscriptions tab in the top menu. My Subscriptions button
  20. Click on the API which you created as shown below.
    subscribed API
  21. Click the API Console menu as shown below to invoke the API with the Store integrated Swagger console.

    click API Console

  22. Click the GET section as shown below.

    GET section

  23. Click Try it out! button as shown below.

    You view the result of invoking the API in the Swagger Console as shown below.
    response body

    Alternatively, you can invoke the API with an external REST client tool such as the  Chrome Advanced REST Client by using the following.

    You view the result of invoking the API in the REST client tool as shown in the example below.

    response in REST client tool

By publishing an existing SOAP/REST service as an API

Follow the steps below to publish an existing SOAP/REST service as an API in the G-Reg Publisher, and view it using the G-Reg Store.

Configuring WSO2 G-Reg to publish the service

Follow the steps below to configure WSO2 G-Reg to publish services on it to WSO2 APIM.

  1.  Log in to the G-Reg Management Console using the following URL and admin/admin credentials:   https://10.100.5.72:9444/carbon

  2. Click Extensions. and then click Lifecycles.
  3. Click the corresponding View/Edit Link of the ServiceLifeCycle as shown below.
    edit the ServiceLifeCycle configuration
  4. Replace the  <execution forEvent="Publish" class="org.wso2.carbon.governance.registry.extensions.executors.apistore.ApiStoreExecutor"> element in the configuration with a code block which defines an execution element in production state as shown in the example below. Add the API Manager credentials in it, so that it provides the API Manager's endpoint, username and password as executor parameters.

    Alternatively you can do this change in the <GREG_HOME>/repository/resources/lifecycles/ServiceLifeCycle.xml  file and then restart the G-Reg server.

    <execution forEvent="Publish" class="org.wso2.carbon.governance.registry.extensions.executors.apistore.ApiStore2Executor">
       <parameter name="apim.endpoint" value="http://localhost:9763/"/>
       <parameter name="apim.username" value="admin"/>
       <parameter name="apim.password" value="admin"/>
       <parameter name="apim.env" value="dev"/>
       <parameter name="default.tier" value="Unlimited"/>
       <parameter name="throttlingTier" value="Unlimited,Unlimited,Unlimited,Unlimited,Unlimited"/>
    </execution>
  5. Click Save.

  6. Click Yes in the message which pops up.

    pop up message

Testing the SOAP/REST service

Follow the steps below to test the SOAP/REST service by creating, publishing and invoking it.

  1. Create a new SOAP service in WSO2 G-Reg. For instructions, see  Creating a SOAP service.

    For instructions on creating  a REST service  to publish it to WSO2 API Manager, see  Creating a REST service.

  2. Publish the SOAP service you created to the APIM Publisher. 

    For instructions on publishing a REST service in WSO2 G-Reg, see Publishing a REST service.

  3. Log in to the G-Reg Publisher using the following URL and admin/admin credentials:  https://10.100.5.72:9443/Publisher
  4. Click on the following icon in the top left corner of the screen.
  5. Click API as shown below.You view the service you created published as an API as shown in the example below.
    published API
  6. Click on the published API of the service.
  7. Click the following EDIT button in the top menu. EDIT button
  8. Repeat steps 6- 23 in the By creating a new API section above, to subscribe and invoke the API.
  • No labels