Adding an API
- Former user (Deleted)
Follow the instructions below to add an API to the store through the API Publisher Web application.
1. Log in to WSO2 API Publisher with a user who has been assigned the "creator" role. For more information on creating users and assigning roles, refer to section User Management.
Once logged in, select the "Add" menu.
In this section, we work with a service exposed by the Cdyne company (www.wdyne.com) which provides data quality services. We use the phone validation service as an example, which has SOAP and REST interfaces and is documented using a WSDL file. This service is described at : http://wiki.cdyne.com/index.php/Phone_Verification.
The table below explains the fields required when adding an API and their descriptions. Also, values are given as an example according to the phone validation service mentioned before. Only the fields marked with * are mandatory.
| FIELD | DESCRIPTION | EXAMPLE VALUES |
|---|---|---|
| Name* | Name of API as you want it to appear in the API store. | PhoneVerification |
| Context* | URI context path that is used by to API consumers. | /phoneverify |
| Version* | API version (in the form of version.major.minor). | 1.0.0 |
| Description | High-level description of API functionality. | Text |
| Visibility | API visibility can be either 'Public' or 'Restricted'. If it is set to 'Public' then the API is visible through the API Store Web application to all API subscribers and also anonymous users of the API store. Alternatively, it can be set to 'Restricted' and specific user roles that have access to the API through the API Store can be set as a comma-separated list (no spaces) in the 'Visible to Roles' text box that appears. Note: If you specify "subscriber" role here, any user who self-subscribes to the API Store will be able to access the API, since users are assigned the "subscriber" role that comes by default with the WSO2 API Manager when they sign-up to the API Store. | Public |
| Thumbnail Image | Icon to be displayed in API store (can be jpeg, tiff, png format). | Image file |
| Endpoint Type* | Secured endpoint or Non secured endpoint. Default is non secured endpoint. If secured endpoint is selected, user will be asked for credentials of the backend service. | Secured |
| Production URL* | Endpoint of the back-end service URL, here: http://ws.cdyne.com/phoneverify/phoneverify.asmx | URL |
| Credentials | If secured endpoint is selected as the "Endpoint Type" above, user will be asked for credentials of the backend service. | |
| Sandbox URL | Endpoint of sandbox (testing) back-end service. A sandbox URL is meant to be used for online testing of an API with easy access to an API key. | URL |
| WSDL | URL of WSDL file (describing API interface): http://ws.cdyne.com/phoneverify/phoneverify.asmx?wsdl | URL |
| WADL | URL to WADL file (describing API interface). | URL |
| Tags | One of more tags separated by comma. Tags are used to group/search for API. | String |
| Tier Availability* | The section below describes this in detail. | Bronze/Gold/Silver/Unlimited |
Business Owner and Email | Information about the person responsible for this API at a business level. | String |
Technical Owner and Email | Information about the person responsible for this API at a technical level. | String |
| API Resources | The section below describes this in detail. |
Note
When the user tries to send requests to a secured endpoint, he may face "Hostname verfiication failed" exception. To overcome this, set <parameter name="HostnameVerifier"> parameter to "AllowAll" in $CARBON_HOME/repository/conf/axis2/axis2.xml file's HTTPS transport sender configuration. For example,
<parameter name="HostnameVerifier">AllowAll</parameter>
This parameter is used to verify the hostname of the certificate of a server when APIManager is acting as a client and doing outbound service calls.
Tags
An API can be given any number of tags by entering a comma-separated list of words. Tags allow you to group/categorize APIs having similar attributes/behavior/domain. Once this API gets published to the API Store, these tags will appear as clickable links to the API consumers, who can use them to quickly jump into the APIs they are interested in.
API-Level Throttling
An API can be available to a consumer at different levels of service facilitated by throttling tiers. Throttling tiers are used to limit the number of hits to an API during a given period of time, typically in cases of infrastructure limitations, security concerns (preventing DOS attacks) etc.
For example, if you have infrastructure limitations in facilitating more than a certain number of requests to an API at a time, throttling tiers can be set to the APIs accordingly. Each tier defines a maximum number of requests per minute. WSO2 API Manager comes with three default tiers, which are 'Gold', 'Silver' and 'Bronze' as defined below:
- Bronze - Allows 1 request for the API per minute.
- Silver - Allows 5 requests for the API per minute.
- Gold - Allows 20 requests for the API per minute.
In addition, there is also a special tier called 'Unlimited' which allows unlimited access. It can be disabled by editing the <TierManagement> node of the api-manager.xml file. For more information on file-based configurations, refer to api-manager.xml configurations.
When creating an API, you can select multiple entries from the list of default tiers. Also, you can add your own tiers to the API Manager using the instructions in section Adding New Throttling Tiers. At subscription time, the consumers of the API can choose which tier they are interested in. Accordingly, the subscriber is granted a maximum number of requests as defined in the tier he/she selected. For information on subscribing to a published API as an API consumer, refer to section Subscribing to an API.
Throttling can also be set at the application-level.
API Resources
When adding a new API using the API Publisher, you can define API resources, which appear at last in the "Add New API" window as follows:
An API is made up of one or more resources. Each resource handles a particular type of request and is analogous to a method (function) in a larger API.
API resources can accept following attributes:
| URL Pattern | |
|---|---|
| HTTP Verb | The HTTP methods which specify the desired action to be performed on the resource. These methods can be GET, POST, PUT, DELETE or OPTIONS. Multiple methods can be selected. |
| Auth Type | Facilitates resource-level authentication where different levels of authentication can be specified to each HTTP method of the resource. |
| Action | Allows to move the resource up and down the list or delete it. |
Once a request is accepted by a resource, it will be mediated through an in-sequence. Any response from the back-end is handled through the out-sequence. Fault sequences are used to mediate errors that might occur in either sequence. Default in-sequence, out-sequence and fault sequence are generated when the API is published.
2. Once the required information is filled, click the "Create" button at the end of the page to create the API.
The API creation process hangs when attempting to create an API for the first time in APIM 1.3.1 using IE version 8 Web browser. This is a known issue, which is fixed in APIM 1.4.0 release onwards.
3. If the API is created successfully, you will be navigated to the "Browse" menu where the newly-added API will be listed with the other available APIs. For example,
4.Click the API to access its information. You will be first navigated to its "Overview" page.
The following tabs are available:
- Overview: Displays the details of the API.
- Edit: Allows the user to change the API details and test the Endpoint URL, Sandbox URL, WSDL and WADL.
- Versions: Shows usage and subscription statistics of the API per version.
- Docs: Allows to add documents to an API. For instructions, refer to section Adding API Documentation.
- Users: Shows the list of active users subscribed to the API and their subscription statistics.
Note
The "Edit" tab is only visible to users with "creator" privileges. Users logged in as creators do not have permission to publish the API. To publish, you need to log in as a user with "publisher" privileges.
Using these tabs, you can manage your API.