Saturday, December 28, 2013

Migrating WSO2 API Manager 1.5.0 to 1.6.0

WSO2 API Manager latest version 1.6.0 got released recently. This post provides instructions on how to migrate your data from API Manager 1.5.0 to 1.6.0. If you had already used API Manager 1.5.0 and need to migrate your data to the latest version you can follow this.

You can download WSO2 API Manager 1.6.0 from here.


You can download the latest migration scripts from

https://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/products/apimgt/1.6.0/modules/distribution/resources/migration-1.5.0_to_1.6.0


Checkout the migration kit by executing below command.

%> svn co https://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/products/apimgt/1.6.0/modules/distribution/resources/migration-1.5.0_to_1.6.0


  1. Shutdown AM 1.5.0 if it is running. 
  2. Backup your API Manager Databases of your AM 1.5.0 instance.
  3. Execute relevant sql script in migration-1.5.0_to_1.6.0 against your API Manager Database. (ex:If your database is mysql run mysql.sql against your APIM mysql database)
  4. Now point same WSO2 Carbon Database(User Store and Registry) and API Manager Databases of your AM 1.5.0 instance to AM 1.6.0. (Configure AM_1.6.0/repository/datasource/master-datasources.xml to point same databases configured in AM 1.5.0)
  5. Move all your synapse configurations to APIM_1.6.0. For that, copy and replace APIM_1.5.0/repository/deployment/server/synapse-config/default directory to APIM_1.6.0/repository/deployment/server/synapse-config/default. [If you had APIs created by tenants copy tenant configs as well which can be found in repository/tenants]
  6. Start AM 1.6.0 and Login.
  7.  Change the registry extension file[.rxt file] with the new one[which can be found from /rxt/api.rxt]. For that go API Manager Management console. Navigate to path 'Home-> Extensions-> Configure-> Artifact Types' from management console and click the link 'View/Edit' and replace above mentioned new api.rxt and save.
  8. Configure endpoint-migration/build.xml with the information for the below properties.
    • registry.home= Path to AM pack location [In a distributed setup, give the Publisher node path]
    • username= Username for the AM server
    • password= Password for the AM server
    • host= IP of running AM server [In a distributed setup, give the host of the Publisher node]   
    • port= Port of running AM server [In a distributed setup, give the port of the Publisher node]   
    • version= Version of AM server
  1. Go inside endpoint-migration/ and execute "ant run". You should get a "BUILD SUCCESSFUL" message if it ran correctly.

Hope this instructions help you to migrate your data from API Manager 1.5.0 to 1.6.0. Queries are welcome if you face any issues with the migration.



Wednesday, December 4, 2013

WSO2 API Manager- Customizing Store User Sign-up

WSO2 API Manager Store Sign-up page can be customized according to your requirements by adding new fields or modifying existing fields. These fields are known as user claims.

By default API Store Sign-up looks as below.



Let's say you want to add a new field called 'Organization' to Store Sign-up page. This post provides step by step instructions on how to achieve this.

1. Start API Manager 1.5.0 and go to Management Console (https://localhost:9443/carbon/)

2. Go to Configure -> Claim Management


3. Click on first Claim dialect displayed as 'http://schemas.xmlsoap.org/ws/2005/05/identity'. This will list all the existing claims under selected dialect. 

4. Click on 'Add New Claim Mapping'. 

5. Enter the below values for new claim.


Display Name : Organization
Description : Organization
Claim Uri : http://schemas.xmlsoap.org/ws/2005/05/identity/claims/organization
Mapped Attribute : organization
Supported by Default : select

Note that claims which are 'Supported by Default' true, are only displayed in the Sign-up page. Therefore when you are adding new claims make sure to check 'Supported by Default' checkbox.



If you need this claim to be a required field [Mandatory field in Sign-up], make sure to check 'Required' checkbox.

6. Open wso2am-1.5.0/repository/deployment/server/jaggeryapps/store/site/conf/locales/jaggery/locale_default.json and add new entry 'Organization' as below. Then Save.

7. Go to API Store Sign-up page and refresh. You can see the newly added field.



Modifying Existing Claims

Let's say now you want to make the Organization field 'required'. Also you want to change the field display order. 

1. Click on Organization Claim and check 'required' as below. Set the Display Order as 4. 

Edit Claim

Check Required

Also I have changed the display order of all the below field such that given numbers are entered for each claim 'Display Order'

First Name : 1
Last Name : 2
Email : 3
Organization : 4



2. Now Access the API Store Sign-up page. You will see the modifications in the display order and Organization field as 'required'.




Thursday, November 7, 2013

Migrating WSO2 API Manager 1.4.0 to 1.5.0


Migrating WSO2 API Manager 1.4.0 to 1.5.0

WSO2 API Manager latest version 1.5.0 got released recently. This post provides instructions on how to migrate your data from API Manager 1.4.0 to 1.5.0. If you had already used API Manager 1.4.0 and need to migrate your data to the latest version you can follow this.

You can download WSO2 API Manager 1.5.0 from here.

You can download the latest migration scripts from https://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/products/apimgt/1.6.0/modules/distribution/resources/migration-1.4.0_to_1.5.0/

Checkout the migration kit by executing below command.

%> svn co https://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/products/apimgt/1.6.0/modules/distribution/resources/migration-1.4.0_to_1.5.0/



1. Shutdown APIM 1.4.0 if it is running.

2. Backup your WSO2 Carbon Database(User Store and Registry) and API Manager Databases of your APIM 1.4.0 instance.

3. Execute relevant sql script in 'migration-1.4.0_to_1.5.0/userstore_db' directory against your WSO2 Carbon Database. This will migrate tables and data in your jdbc user store.

4. Execute relevant sql script in 'migration-1.4.0_to_1.5.0/apimgt_db' directory against your API Manager Database.

5. Now point same WSO2 Carbon Database(User Store and Registry) and API Manager Databases of your AM 1.4.0 instance to AM 1.5.0.
(Configure AM_1.5.0/repository/datasource/master-datasources.xml to point same databases configured in AM 1.4.0)

6. Open AM_1.5.0/repository/conf/user-mgt.xml and add the property to existing 'AuthorizationManager' configuration.


true
ex:

            /permission
     true
     true


7. Move all your synapse configurations to APIM_1.5.0. For that, copy and replace APIM_1.4.0/repository/deployment/server/synapse-config/default directory to APIM_1.5.0/repository/deployment/server/synapse-config/default

8. Start APIM 1.5.0


Wednesday, October 2, 2013

How to add additional headers to WSO2 API Manager Swagger Console

WSO2 API Manager has integrated Swagger to allow API consumers to explore APIs through a interactive console.

When integrating Swagger with WSO2 API Manager we had to support CORS between API Store and the API Gateway. So in order to send any headers from Swagger, we need to add those required headers to the response coming from the API Gateway as 'Access-Control-Allow-Headers' . By default below set of headers are allowed to be send from swagger.

authorization,Access-Control-Allow-Origin,Content-Type

So if you need to add any additional headers to Swagger UI, then we should add that header to list of 'Access-Control-Allow-Headers'.

There are 2 options to modify 'Access-Control-Allow-Headers'.

1. Modify the Synapse configuration of APIs and add modified set of headers to OutSequence.

If you choose this method, you have to modify API configuration of each API and add the 'Access-Control-Allow-Headers'. For that go to Management Console of API Manager and then Go to Source View. Then modify the OutSequence with Access-Control-Allow-Headers property setting required headers as the value.

For example let's say the additional header wee need to add is 'Action', then outSequence should be modified as below.




2. Modify API templates.

Inside API Manager distribution you can find templates for APIs from APIM_HOME/repository/resources/api_templates. By modifying outSequences of below template files in there, all the APIs created thereafter will get the modified outSequence.

api_templates_complex_resource.xml
api_templates_complex_resource_with_jwt.xml
api_templates_resource.xml
api_templates_resource_with_jwt.xml


        
        




Once you have followed one of the above approaches, then you will be able to send those headers through swagger UI. So only thing left to do is adding the header parameter to API definition. For that go to API Publisher and select required API. Go to 'Docs' tab and click 'Edit Content' for API definition.


Then add required header parameter to available parameter list of the required operation/s.

ex:

                     {
                            "name": "Action",
                            "description": "SoapAction",
                            "paramType": "header",
                            "required": false,
                            "allowMultiple": false,
                            "dataType": "String"
                        }

Once you saved this, you will be able to see the added header parameter in the Swagger UI.