This documentation is for WSO2 API Manager 1.7.0 View documentation for the latest release.
Quick Start - API Manager 1.7.0 - WSO2 Documentation

All docs This doc
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 24 Next »

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 deployment immediately.

This guide walks you thorough the main usecases of the API Manager:

Introduction to basic concepts

Let's take a look at the basic concepts that you need to know before using the API Manager:

Components

The API manager comprises the following components:

  • API Gateway : Secures, protects, manages, and scales API calls. It is a simple API proxy that intercepts API requests and applies policies such as throttling and security checks. It is also instrumental in gathering API usage statistics. The Web interface can be accessed via https://<Server Host>:9443/carbon.
  • API Key Manager : Handles all security and key-related operations. API gateway connects with the key manager to check the validity of OAuth tokens when APIs are invoked . Key Manager also provides a token API to generate Oauth tokens that can be accessed via the Gateway.
  • API Publisher : Enables API providers to publish APIs, share documentation, provision API keys, and gather feedback on API features, quality and usage. The Web interface can be accessed via https://<Server Host>:9443/publisher.
  • API Store : Enables API consumers to self register, discover API functionality, subscribe to APIs, evaluate them and interact with API publishers. The Web interface can be accessed via https://<Server Host>:9443/store.
  • Additionally, statistics are provided by the monitoring component, which integrates with WSO2 BAM.

Users and roles

The API manager offers three distinct community roles that are applicable to most enterprises:

  • Creator : a creator is a person in a technical role who understands the technical aspects of the API (interfaces, documentation, versions, how it is exposed by API Gateway) and uses the API publisher to provision APIs into the API store. The creator uses the API Store to consult ratings and feedback provided by API users. Creator can add APIs to the store but cannot manage their lifecycle (i.e., make them visible to the outside world).
  • Publisher : a publisher manages a set of APIs across the enterprise or business unit and controls the API lifecycle and monetization aspects. The publisher is also interested in usage patterns for APIs and as such has access to all API statistics.
  • Consumer : a consumer uses the API store to discover APIs, see the documentation and forums and rate/comment on the APIs. S/he subscribes to APIs to obtain API keys.

API lifecycle

An API is the published interface, while the service is the implementation running in the backend. APIs have their own lifecycles that are independent to the backend services they rely on. This lifecycle is exposed in the API publisher Web interface and is managed by the API publisher role.

The following stages are available in the default API life cycle:

  • CREATED : API metadata is added to the API Store, but it is not visible to subscribers yet, nor deployed to the API gateway
  • PUBLISHED : API is visible in the API Store
  • DEPRECATED : API is still deployed into the API Gateway (i.e., available at runtime to existing users) but not visible to subscribers. An API can automatically be deprecated when a new version is published.
  • RETIRED : API is unpublished from the API gateway and deleted from the store
  • BLOCKED : Access is temporarily blocked. Runtime calls are blocked and the API is not shown in the API Store anymore.

You can manage the API and service lifecycles in the same governance registry/repository and automatically link them. This feature is available in WSO2 Governance Registry (version 4.5 onwards).

Applications

An application is primarily used to decouple the consumer from the APIs. It allows you to :

  • Generate and use a single key for multiple APIs
  • Subscribe multiple times to a single API with different SLA levels

You create an application to subscribe to an API. The API Manager comes with a default application and you can also create as many applications as you like.

Throttling tiers

Throttling tiers are associated to an API at subscription time. They define the throttling limits enforced by the API gateway. E.g., 10 TPS (transactions per second). You define the list of tiers that are available for a given API at the publisher level. The API Manager comes with three predefined tiers (Gold/Silver/Bronze) and a special tier called Unlimited, which can be disabled by editing the <TierManagement>element of <PRODUCT_HOME>/repository/conf/api-manager.xml file. To edit existing tiers or create your own tiers, see Adding New Throttling Tiers.

API keys

The API Manager supports two scenarios for authentication:

  1. An access token is used to identify and authenticate a whole application
  2. An access token is used to identify the final user of an application (for example, the final user of a mobile application deployed on many different devices)

Application access token

Application access tokens are generated by the API consumer and must be passed in the incoming API requests. The API Manager uses OAuth2 standard to provide key management. The API key is a simple string that you pass to an HTTP header (e.g., "Authorization: Bearer NtBQkXoKElu0H1a1fQ0DWfo6IX4a") and it works equally well for SOAP and REST calls.

Application access tokens are generated at the application level and valid for all APIs that are associated to the application. These tokens have a fixed expiration time, which is set to 60 minutes by default. You can change this to a longer time, even for several weeks. Consumers can re-generate the access token directly from the API Store Web interface. To change the default expiration time, you open <APIM_HOME>/repository/conf/identity.xml file and change the value for element <ApplicationAccessTokenDefaultValidityPeriod>. You set a negative value to <ApplicationAccessTokenDefaultValidityPeriod> element to never expire the application access token.

Application user access token

You can generate access tokens on demand using the token API. In case a token expires, you use the token API to refresh it.

Application user access tokens have a fixed expiration time, which is 60 minutes by default. You can update it to a longer time, such as several weeks, by editing the <AccessTokenDefaultValidityPeriod> element in <APIM_HOME>/repository/conf/identity.xml file.

The token API takes the following parameters to generate the access token:

  • Grant Type
  • Username
  • Password
  • Scope

To generate a new access token, you issue a token API call with the above parameters where grant_type=password. The Token API then returns two tokens: an access token and a refresh token. The access token can then be stored in a session on the client side (the application itself does not need to manage users and passwords). On the API Gateway side, the access token is validated for each API call. When the token expires, you refresh the token by issuing a token API call with the above parameters where grant_type=refresh_token and passing the refresh token as a parameter.

Creating users and roles

In section   Users and roles , we introduced you to a set of users that are commonly found in many enterprises. To create these users in the API Manager, you log in to the management console as an administration user (credentials: admin/admin). The admin use can play the creator, publisher and subscriber roles described earlier. In this section, we explain how to set up these users or custom users and roles.

  1. Log in to the management console (https://hostname:9443/carbon) using admin/admin credentials.
  2. Select the Users and Roles menu under the Configure menu.
  3. Click Add New Role and provide creator as the role name.
  4. Click Next.
  5. Select the following permissions from the list that opens and click Finish.
    • Login
    • Manage > API > Create
    • Manage > Resources > Govern and all underlying permissions
  6. Similarly, create the publisher role with the following permissions.


    • Login
    • Manage > API > Publish
  7. You can now create users for each of those roles. To do so, click the Users and Roles menu under the Configure menu.
  8. Click Users.
  9. Click Add New User, provide the username/password and click Next.
  10. Select the role you want to assign to the user (e.g., creator, publisher or subscriber) and click Finish. Given below is a list of usernames and the roles we assign to them in this guide.

    UsernameRole
    apicreatorcreator
    apipublisherpublisher

    Repeat the steps to create at least one user for all roles.

Creating and publishing APIs

An API creator uses the API provider Web application to create and publish APIs into the API Store. In this section, we explain how to create an API and attach documentation to it.

The Phone Number Validation API

Along this guide, we work with a service exposed by the Cdyne services provider (www.wdyne.com). We use their phone validation service, which has SOAP and REST interfaces and is documented using a WSDL file. This service is documented at : http://wiki.cdyne.com/index.php/Phone_Verification.

Let's create this API and add it to the API Store.

  1. Open the API Publisher (https://<YourHostName>:9443/publisher) and log in as apicreator.
  2. Click the Add link and provide the information in the table below to your API.

    FieldValueDescription
    Name
    PhoneVerification
    Name of API as you want it to appear in the API
    store
    Context
    /phoneverify
    URI context path that is used by to API consumers
    Version1.0.0API version (in the form of version.major.minor)
    DescriptionTextHigh level description of API functionality
    VisibilityPublic/Restricted
    If the API can be accessed by everyone, then select the visibility as 'Public'. Else select it as 'Restricted' and enter the user roles to which the API can be accessible
    from both API publisher and store.
    Thumbnail Image
    Image file
    Icon to be displayed in API store (can be jpeg, tiff, png format)
    Endpoint Security Scheme
    Non-Secured/Secured
    If the back-end service is a secured service, select 'Secured' and enter the credentials for secured service in appearing text boxes. Else keep as Non-Secured.
    Endpoint TypeSelect
    Endpoint Type. E.g., High available and load balanced endpoints
    Production URLURL
    Endpoint of the back-end service URL, here:
    Sandbox URLURL
    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.
       
  3. as
  • No labels