Page History

...

Swagger-based interactive documentation allows you to try out APIs from the documentation itself. It is a Java Script client that runs in the API Store and makes Java Script calls from the Store to the API Gateway. Since the API Store and Gateway run on two different ports, you must enable cross-origin resource sharing (CROSCORS) between the two using CORS configuration in <APIM_HOME>/repository/conf/api-manager.xml file. Given below is a sample configuration of CROS CORS and a description of its XML elements:

<CORSConfiguration>
    <Enabled>true</Enabled>
    <Access-Control-Allow-Origin>https://localhost:9443,http://localhost:9763</Access-Control-Allow-Origin>
    <Access-Control-Allow-Headers>authorization,Access-Control-Allow-Origin,Content-Type</Access-Control-Allow-Headers>

    <!--Configure Access-Control-Allow-Methods-->
    <Access-Control-Allow-Methods>GET,POST,PUT,DELETE,OPTIONS</Access-Control-Allow-Methods>

    </CORSConfiguration>

...

1. Log in to API Publisher Web interface (https://localhost:9443/publisher), and go to Add API page. Create a new API with following information by navigating to each tab.
   For
   • Name: PhoneVerification
   • Context: /phoneverify
   • Version: 1.0.0
   • Choose to create a wildcard resource (/*)
   • Endpoint type: HTTP
   • Production Endpoint: http://ws.cdyne.com/phoneverify/phoneverify.asmx
   • Tier availability: Bronze/Gold/Silver/Unlimited
   • Transports: HTTP/HTTPS
   Define API resources for the operations you need to perform.
   

   Specify None as the Auth Type of OPTIONS

   • 
     Image Added

   Tip
   In the Manage screen, you can specify an authentication type for the methods of the resource that you created earlier.  For each of the resource that has HTTP verbs requiring Authentication (i.e., Auth Type is not NONE),

   enable

   enable OPTIONS

   with

   with None

   Auth

   Auth type. For example, as the following screen shot shows, resources with /* URL Pattern has HTTP verbs with Auth Type

   as

   as Application & Application User. Therefore, we must

   give

   give None

   as

   as the Auth Type

   of

   of OPTIONS. This is to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway. But, if no authentication is needed for any of the HTTP verbs, you don't have to

   specify

   specify None

   Auth

   Auth type

   to

   to OPTIONS.

   Image Removed

   Image Added

2. Publish the API to the API Store.

...

1. Log in to the API Publisher, go to the Doc tab of PhoneVerify API and click Edit Content under Swagger Documentation.
   

2. The API definition opens. Note that the API definition contains its JSON representation.

   • By default, all the POST and PUT operations have a Payload parameter, which you can use to send any payload when invoking the API.
   • You can use the Query parameters in GET, DELETE operations to send URL-appended values (e.g.,: v=2&length=200).

3. Modify existing content, add/remove elements, change paths and parameters of the API definition using either of the following editors: Text Editor or the Graphical Tree Editor.

   Info
   API Manager 1.5.0 onwards has integrated JSONMate as the editor for modifying the API Definition. For the Swagger specification of API declaration, see  https://github.com/wordnik/swagger-core/wiki/API-Declaration.

   The example below shows how we have changed the path for all the HTTP methods of the API definition from /phoneverify/1.0.0/ to /phoneverify/1.0.0/CheckPhoneNumber using both the text editor and graphical tree editor:

4. After the modifications are done, click save.

Invoking the interactive documentation

1. Log in to the API Store Web interface (https://localhost:9443/store) and click the API published before.
2. Subscribe to the API using the Bronze tier.
   Image RemovedImage Added
3. Generate the access tokens. You need them to invoke the API in the next steps.

4. Select the API again and go to the API Console tab, which shows the interactive documentation of the API. Using the API console, you can modify existing content, add/remove elements, change paths and parameters etc. using the JSON editor.

   Info
5. WSO2 API Manager 1.5.0 onwards has integrated JSONMate as the editor for modifying the API Definition.
For the Swagger specification

of

API declaration, see https://github.com/wordnik/swagger-core/wiki/API-Declaration.

By default, all the POST and PUT operations have the Payload parameter, which you can use to send any payload when invoking the API. The GET, DELETE operations have Query parameters, which you can use to send URL-appended values. You can also add named parameters. For example, to modify the path of the API created above with a parameter, edit the path and add the relevant parameter.

6. Provide the necessary parameters and click Try it out to call the API. For example, the PhoneVerification API takes two parameters: the phone number and a license key, which is set to 0 for testing purposes.
   
   
   Note the following in the above UI:
   

   Base URL	Appears at the bottom of the console. Using the base URL and the parameters, the system creates the API URL in the form http://host:8280/<context>/<version>/<back end service requirements included as parameters>. For example, http://host:8280/phoneverify/1.1.0/CheckPhoneNumber.
   Query Parameters	Give the API payload as PhoneNumber=18006785432&LicenseKey=0 where /phoneverify is the context and 1.1.0 is the version. The rest of the URL is driven by the backend service requirements.
   Authorization	In the authorization header, pass the application key that was generated at the time a user subscribes to an API. This is prefixed by the string "Bearer". For example, Bearer q6- JeSXxZDDzBnccK3ZZGf5_AZTk. WSO2 API Manager enforces OAuth security on all the published APIs. Consumers who talk to the API Manager should send their credentials (application key) as per the OAuth bearer token profile. If you don't send an application key or send a wrong key, you will receive a 401 Unauthorized response in return.

    

7. Note the response for the API invocation that appears as follows:
    
8. Within a minute after the first API invocation, make another attempt to invoke the API and note that the second invocation results in a throttling error.
   
   This is because you applied a Bronze tier at the time you subscribed to the API and the Bronze tier only allows one API call per minute.