Page Comparison

WSO2 API Manager is a complete solution for publishing APIs, creating and managing a developer community and for routing API traffic in a scalable manner. It leverages the integration, security and governance components from the WSO2 Enterprise Service Bus, WSO2 Identity Server, and WSO2 Governance Registry. In addition, as it is powered by the WSO2 Business Activity Monitor (BAM), the WSO2 API Manager is ready for massively scalable deployments immediately.

...

1. Open the API Publisher (https://<hostname>:9443/publisher) and log in as apicreator.

2. Click the Add link and provide the information given in the table below. Click Implement once you are done.
   

   Field		Sample value
   Name		PhoneVerification
   Context		/phoneverify
   Version		1.0.0
   Visibility		Public
   Resources	URL pattern	CheckPhoneNumber
   	Request types	GET, POST, OPTIONS

   

3. Give the following information in the Implement tab that opens and click Manage once you are done.

   Field	Sample value
   Implementation method	Backend
   Endpoint type	HTTP
   Production endpoint	In this guide, we work with a service exposed by the Cdyne services provider. We use their phone validation service, which has SOAP and REST interfaces. Endpoint is http://ws.cdyne.com/phoneverify/phoneverify.asmx.  This sample service has two operations as CheckPhoneNumber and CheckPhoneNumbers. Let's use CheckPhoneNumber here.
   Endpoint security scheme	Non Secured (If secured, user is asked for credentials of the backend service)

   

4. Click Manage to go to the Manage tab and provide the following information. 

   Field	Value	Description
   Tier Availability	Bronze/Gold/Silver/Unlimited	The API can be available at different level of service; you can select multiple entries from the list. At subscription time, the consumer chooses which tier they are interested in.

   

   Tip
   Tip: For resources that have methods requiring authentication (i.e., Auth Type is not NONE), you set  None  as the Auth type of OPTIONS to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway.

5. Once you are done, click Save and Publish. 

6. Go to the API Store (https://<hostname>:9443/store) and note that the API you just published is listed there.
   Image Removed

Adding API documentation

1. After saving the API, click on its thumbnail in the API Publisher to open it.

2. Click on the API's Docs tab and click the Add New Document link.
   

3. The document options appear. Note that you can create documentation inline, via a URL or as a file. For inline documentation, you can edit the content directly from the API publisher interface. You get several documents types:

   • How To
   • Samples and SDK
   • Public forum / Support forum (external link only)
   • API message formats
   • Other

4. Create a 'How To,' using in-line content as the source. The document name is SimpleClient and click the Add Document button.
   

5. Once the document is added, click Edit Content link associated with it to opens an embedded editor.
   

6. Enter your API's documentation.
   

Versioning the API

Let's create a new version of this API.

1. Log in to the API Publisher as apicreator if you are not logged in already.
2. Click on the PhoneVerification API and then the Copy button that appears in its Overview tab.
   Image Removed

3. Give a new version number (e.g., 2.0.0) and click Done.
   Image Removed

   Tip

   Tip: The Default Version option means that you make this version the default in a group of different versions of the API. A default API can be invoked without specifying the version number in the URL. For example, if you mark http://host:port/youtube/2.0 as the default version when the API has 1.0 and 3.0 versions as well, requests made to http://host:port/youtube/ get automatically routed to version 2.0.  If you mark any version of an API as the default, you get two API URLs in its Overview page in the API Store. One URL is with the version and the other is without. You can invoke a default version using both URLs. If you mark an unpublished API as the default, the previous default, published API will still be used as the default until the new default API is published (or prototyped).

A new version of the API is created. It is a duplication of all the original API, including its documentation. The PhoneVerification 2.0.0 API is now ready to be published. This is typically done by a user in the publisher role.

Publishing the API

...

• Propagate Changes to API Gateway: Used to define an API proxy in the API Gateway runtime component, allowing the API to be exposed to the consumers via the API Gateway. If this option is left unselected, the API metadata will not change and you will have to manually configure the API Gateway according to the information published in the API Store.
• Deprecate Old Versions: If selected, any prior versions of the API will be set to the DEPRECATED state automatically.
• Require Re-Subscription: Invalidates current user subscriptions, forcing users to subscribe again.

...

Adding interactive documentation

The API Manager provides facility to add interactive documentation support through the integration of Swagger. Swagger is a specification and a complete framework implementation for describing, producing, consuming, and visualizing RESTful Web services. In Swagger, when APIs are described in simple static JSON representation, they can be loaded through the Swagger UI, which in turn provides the interactive documentation.

When an API is created, the JSON representation of that API is automatically generated and saved into the registry as API definition. This definition describes the API with the information provided at the API creation level. You can customize the automatically generated API definition as follows:

...

When the Swagger definition of the API opens, document the parameters required by the API Console.
For example, the PhoneVerification API requires a telephone number and a license key. You can document this by adding the following under the parameters section of the GET method:

parameters:
   - description: Request Body
     name: body
     allowMultiple: false
     required: true
     type: string
     paramType: body
   - description: Give the phone number to be validated
     name: PhoneNumber
     type: string
     required: "True"
     paramType: query
   - description: "Give the license key. If you don't have any, enter 0"
     name: LicenseKey
     type: string
     required: "True"
     paramType: query

...

Adding interactive documentation

The API Manager provides facility to add interactive documentation support through the integration of Swagger. Swagger is a specification and a complete framework implementation for describing, producing, consuming, and visualizing RESTful Web services. You describe APIs in simple, static JSON representation through the Swagger API definition in the API Store. When an API is created, the JSON representation of that API is automatically generated and saved in the registry. This definition reflects the information you provide at the API creation stage. You can customize it as follows:

1. Open the API Publisher (https://<hostname>:9443/publisher) and log in as apicreator if you haven't done so already.
2. Click the PhoneVerification API to open it and then click the Edit link right next to the API's name. This opens the API in its edit mode.
   Image Added
3. Click the Edit Swagger Definition button.Image Added

4. When the Swagger definition of the API opens, document the PhoneNumber and LicenseKey parameters that you added to the GET method at the time the API was created.

   Code Block
   parameters: - description: Request Body name: body allowMultiple: false required: true type: string paramType: body - description: "Give the phone number to be validated" name: PhoneNumber type: string required: "True" paramType: query - description: "Give the license key. If you don't have any, enter 0" name: LicenseKey type: string required: "True" paramType: query

   
   Image Added

5. Click Save once the changes are done.

Versioning the API

Let's create a new version of this API.

1. Log in to the API Publisher as apicreator if you are not logged in already.
2. Click on the PhoneVerification API and then the Copy button that appears in its Overview tab.
   Image Added

3. Give a new version number (e.g., 2.0.0) and click Done.
   Image Added

   Tip

   Tip: The Default Version option means that you make this version the default in a group of different versions of the API. A default API can be invoked without specifying the version number in the URL. For example, if you mark http://host:port/youtube/2.0 as the default version when the API has 1.0 and 3.0 versions as well, requests made to http://host:port/youtube/ get automatically routed to version 2.0.  If you mark any version of an API as the default, you get two API URLs in its Overview page in the API Store. One URL is with the version and the other is without. You can invoke a default version using both URLs. If you mark an unpublished API as the default, the previous default, published API will still be used as the default until the new default API is published (or prototyped).

A new version of the API is created. It is a duplication of all the original API, including its documentation. The PhoneVerification 2.0.0 API is now ready to be published. This is typically done by a user in the publisher role.

Publishing the API

1. Log in to the API Publisher as apipublisher that you created earlier in this guide.
2. Click on the PhoneVerification API version 2.0.0. Note that you now see a tab by the name Lifecycle in the API Publisher UI.
3. Go to the Lifecycle tab and select the state as PUBLISHED from the drop-down list.
   Image Added
   The three checkboxes mean the following:
   
   • Propagate Changes to API Gateway: Used to define an API proxy in the API Gateway runtime component, allowing the API to be exposed to the consumers via the API Gateway. If this option is left unselected, the API metadata will not change and you will have to manually configure the API Gateway according to the information published in the API Store.
   • Deprecate Old Versions: If selected, any prior versions of the API will be set to the DEPRECATED state automatically.
   • Require Re-Subscription: Invalidates current user subscriptions, forcing users to subscribe again.
4. You have now deprecated an older version of an API and published a new version. Go back to the API Store and note that PhoneVerification 1.0.0 is not visible under the APIs menu because it is deprecated. You can see the PhoneVerification 2.0.0 API.
   Image Added

Subscribing to the API

You subscribe to APIs using the API Store Web application.

...