IBM API Management introduction
This chapter provides an overview of IBM API Management and its approach to enabling businesses to expose APIs internally and externally.
This chapter contains the following topics:
A scenario that exemplifies the use of APIs and a mobile application that uses those APIs is described. Throughout this book, the use of IBM API Management is exemplified by developing this scenario.
2.1 Introduction to IBM API Management
IBM API Management is a complete on-premises solution enabling companies to rapidly create, socialize, and manage APIs. It covers the following key areas through a configuration, not through coding:
•Security
 – Managing access, both from the front end with application developer security, to the back-end with integration security, to data services.
 – Quota usage, tracking and monitoring
•Capability
 – The design, creation, versioning of APIs
 – Proxy or assembly of existing services
•Caching
 – Dealing with increased load on back-end services
 – Flood control and denial-of-services (DoS) prevention
•Analytics
 – Technical matrix about calls made, devices used, workload per application developer
 – Business level queries defined as needed
•Community
 – Publicize and promote adoption of your APIs
 – Manage the signing up of application developers
 – Provide branding for your enterprise, plus self-service documentation and samples for your users
IBM API Management is designed to remove barriers to the installation and configuration of a scalable, secure, enterprise API Management solution. Installation and configuration details are not given in this book, but the components that form the solution are outlined. API principles and how they can be implemented is also described.
The easy-to-use developer interface and tooling enables developers from a company to make internal applications and services available to a community of application developers and partners through these APIs.
An API typically consists of a request and a response made over HTTP. The templates for different data sources supplied by IBM Web API Services allows a company’s developers to easily identify what parts of an application or service can be accessible through the web API.
The API Management solution provides a robust mechanism for exposing resources and synchronizing with the back-end data needed in those resources. This can be done through a simple proxy mechanism to an existing service, or through the assembly of existing applications and data to create the appropriate actions and responses.
2.2 Deployment topologies
An API Management solution is deployed to facilitate the development of applications (apps). The apps may be created by one or more of the following developers:
•Internal developers behind the firewall
•Third-party trusted developers, for example business partners or mobile app agencies
•Unknown public developers
If the apps are developed internally, then the APIs need not be exposed to external developers, such as the partners or public. An API Management layer is effective in providing a uniform integration layer for internal app developers who wants the straightforward REST/JSON based data access and it complements a SOA strategy.
2.2.1 Mobile enterprise application platforms
For more information about APIs and Mobile applications, see Chapter 11, “Mobile app development” on page 253.
Where mobile apps are developed, a mobile enterprise application platform (MEAP) might be used. The MEAP, such as IBM Worklight, might contain mechanisms and adapters for integration to data services and include accessing HTTP resources such as APIs. The MEAP is typically placed inside the enterprise and protected by a secure gateway.
Using an externally exposed API through the MEAP integration, adapters add latency to the call and thus the mobile application calls the API directly. For internally exposed APIs using the MEAP integration, adapters are used.
2.2.2 Internal API exposure
In this topology, APIs are exposed only to internal app developers.
The topology of exposing the internal APIs is shown in Figure 2-1. Here, the mobile application makes calls to a MEAP adapter (shown as IBM Mobile platform), which then makes the call to the API Management layer or other integration middleware such as an enterprise service bus (ESB).
Figure 2-1 Internal API exposure for mobile applications
2.2.3 External API exposure
Socializing and exposing the APIs is a common approach and requires that the API Management solution is fully secure. The gateway tier within IBM API Management is implemented with IBM DataPower and provides security functionality inherent within that solution. Further information about IBM WebSphere DataPower Appliances is available at the following location:
Control over app developer usage is still possible through approval processes, and only registered developers and their registered applications can gain entitlement to the API resources. The topology for exposing APIs externally for mobile applications is shown in Figure 2-2 on page 19. This differs from Figure 2-1 in that the mobile application makes a call directly to the API Management layer which then provides the integration service to cloud or back-end data sources.
Figure 2-2 Exposing APIs externally
2.3 API Management components
IBM API Management consists of four tiers as shown in Figure 2-3 on page 20:
•Gateway tier
•Management tier
•Analytics tier
•Assembly tier
Each tier is provided for by one or more appliances (purposely built hardware and software devices). Incoming API calls are always directed into the gateway tier.
Figure 2-3 IBM API Management solution components
Gateway tier
The gateway tier is the entry point for all API calls and it handles the security enforcement and entitlements. This requires the authentication and authorization of the call and also payload verification. It also acts as a load balancer for the analytics and Assembly nodes, communicating with those to route the call and to pass analytics information.
Management tier
The management tier provides the configuration interface for other tiers. Internally, it contains a persistent store that saves all the information and orchestrates other tiers. The management tier also serves all user interface applications including Environment Console, API Manager, and Developer Portal.
Analytics tier
The analytics tier is the engine for and stores all data for analytics. Information about the API calls and message are stored here. Because of the amount of information that might be collected, this tier is typically the largest.
The analytics tier also stores monitoring and metric information of the nodes for system management. Interaction with this data is through the Developer Portal and API Manager.
Assembly tier
The IBM API Management solution enables the simple proxy to an existing service or the creation of a new API that includes capability to aggregate data from multiple services and to filter and transform data. The assembly tier is not required if all APIs are simple proxies but it is required when other capability is used.
2.4 IBM API Management solution overview
An API Management solution is required to meet the three areas of creation, management, and exposure of APIs while being fully secure and scalable. This section introduces how IBM API Management meets these needs and references the chapters where each element is detailed.
The user interface for an API Management solution has three sections, all accessible from a web browser:
•Management Interface/Console
The console provides the management functions for the setup of the solution and the configuration of the tiers. It is available at the following location:
<domain name>/console
•API Manager
The API Manager is the main interface for the creation of the APIs and provides the functions for the creation of proxy-only APIs and assembles, security entitlements, analytics, and the build of the Developer Portal. The API Manager is available at the following location:
<domain name>/apimanager
•Developer Portal
The Developer Portal is the user interface for app developers and provides user and application registration, API documentation and entitlement configuration. It is configured from within the API Manager and on publication is available at the following location:
<domain name>/portal
This section focuses on the API Manager. The use of the console is not described in this book. For information about the Developer Portal, see Chapter 9, “Developer Portal” on page 189.
2.4.1 Creating and managing APIs: Overview of the API Manager
The user interface to the API Manager is accessed through a web browser. With this single user interface, you can control all aspects of the development, management, and socialization of APIs including the development and testing of APIs through to security, analytics, and the building of the Developer Portal.
After you sign in to the system, all options are available from the Getting Started menu as shown in Figure 2-4. This page is available using the link provided by the title API Manager in the header. The complete menu is available by clicking the section title (with drop-down arrow) in the section header.
Figure 2-4 Getting Started page of the API Manager
The menu contains three sections, Create, Socialize, and Manage, for API creation, management, and socialization.
2.4.2 API creation
The Create section of the Getting Started menu gives access to the setup of connections and endpoint authentication and also the general section for the APIs. APIs may be created to the same endpoint connection and use the same authentication mechanisms and it is possible to create and manage those here. It is not necessary to initially create the lists of connections or authentication methods at the beginning because these can be created at the time of API definition. To start creating APIs, click Getting Started → APIs.
API definition
An API is first defined by specifying a name, context, and description. When the API is made public, the URL will be formed from the following string:
<domain name>/<context>
After the API is defined, it is listed. Click the API name to access the API page. This page (Figure 2-5) provides access to build the API resources.
Figure 2-5 Overview page of creating a new API
On the APIs page, you can define resources, entitlements and authentication, testing, and version management. If the API is kept private, it can be used only by people with access to the API Manager.
When an API resource is defined, its definition is automatically used for documentation. Additional documentation in the form of a file, for example PDF, or a URL may be added.
API resources
You create an API resource from the Resources tab (Figure 2-6).
Figure 2-6 API Resources tab
When a new resource is added, it is then defined by clicking the name, or the Edit icon. When editing a resource, the Overview tab defines the request and response information, which will form part of the documentation. The response body is defined by using an example of the response that will be sent back. Defining an XML or JSON schema is not necessary. An example of the response is of value to the application developer; the response body entered here automatically forms part of the documentation provided to the developer.
The resource Overview tab is shown in Figure 2-7.
Figure 2-7 API resource overview
An API resource may be defined as a straight proxy to an existing HTTP resource or as an assembly. The assembly capability enables multiple data sources to be called and the returned data to be aggregated and filtered. When creating an assembly, you can integrate directly to databases, cloud applications, HTTP resources through the operations of PUT, GET, POST and DELETE, or invoke web services. The variables created in each call of the assembly are available to the next call.
A sample assembly is shown in Figure 2-8 on page 26.
 
Note: The assembly capability requires implementation of the Assembly tier. If this is not implemented and configured, the Assemble tab is not displayed.
Figure 2-8 Example of an API Assembly
Creation of APIs for proxy and assemblies is detailed in Chapter 3, “Defining APIs” on page 37.
Entitlements, authentication, and authorization
An API resource must have an entitlement specified to be used. Entitlements define a rate limit (the number of calls per time segment), whether the app secret (an additional security token specific to the registered app) is required in addition to the App ID and whether the developer is required to ask for approval. Entitlements are set at the API level and when an API is created, a default entitlement is created for the purpose of testing.
The Entitlements and Authentication tab (Figure 2-9 on page 27) shows the default entitlement and allows the creation of new entitlements. The specification of the authentication method to the endpoint is also specified on this tab. For more details, see Chapter 4, “Entitlements” on page 71.
Access to data may be restricted to groups of users, especially important for private corporate data, for example where a mobile application is written for a customer management system. Security enforcement is a key element of API Management and is covered in Chapter 5, “API security” on page 81.
Figure 2-9 API entitlements
Testing API resources
An API resource may be tested from within the API Manager interface and a test application is available with the default entitlements. The API must be running when a call is made to the full URL with a default app ID.
To test an API resource, click Test to get the test page (Figure 2-10 on page 28).
Figure 2-10 API resource testing within API Manager
API lifecycle
Typically, there will be development, testing, and production environments. APIs can be exported from any environment and then imported into another. If an API of the same name exists in the destination environment, importing that API will not be possible.
Snapshots of an API can be taken and version information are assigned to these snapshots. An API can be replaced with a previous snapshot and a snapshot can be started in preference to the current version.
2.4.3 Socializing APIs: An overview of the Developer Portal
The Developer Portal can be configured through the management interface and published. An application developer accesses the portal through the following URL:
<domain name>/portal
Building the Developer Portal
The building and publishing of the Developer Portal has been made to be rapid and easy with a configuration and customization-based user interface that does not require programming skills. When customized, the portal can be published with a single click.
The Developer Portal can be customized from the Socialize menu. From here, the portal layout can be configured and graphics added. Links to social media can also be set up. Figure 2-11 shows an example of customizing the portal.
Figure 2-11 Developer Portal customization
Information regarding terms, conditions, and support can be added here. Documentation for the API is created automatically when the API is configured and added, in the form of documents, to the API configuration.
Developer access to the Developer Portal
Documentation for the APIs is available to anyone accessing the portal home page at the following location:
<domain_name>/portal
To gain entitlement to the API and to use the API, a developer must register and sign in. The developer can then register applications, sign up to entitlements, test the APIs, and view a dashboard of their usage. The developer home page that enables these features is shown in Figure 2-12.
Figure 2-12 Developer Portal home page
2.4.4 Management
As described in 2.3, “API Management components” on page 19 the IBM API Management solution consists of four tiers. The setup and configuration of these tiers and the analysis of logs and statistics is provided through the management console at the following location:
<domain name>/console
When installed, configured, and running, the tier infrastructure can be scaled by adding more nodes into each tier; each node being an additional appliance. Load balancing is automatic and provided for by the gateway tier or can be handled externally to the system.
A detailed explanation of the installation and setup of the system is out of scope for this book. A guide to the requirements and installation of the solution is available in the information center:
Analytics
All activity within the IBM API Management solution is logged and stored in the Analytics Tier. The information specific to the app developer is made available through the Developer Portal to that app developer. All other information about API usage, activity logs, and error logs is available from the API Manager, which provides the user interface for analyzing this information.
The analytics information is provided in three areas:
•API Manager Dashboard
The dashboard provides high level and drill-down capability to the API calls that have been made. Calls are shown for each API, developer, application, and client device. An example is shown in Figure 2-13 on page 32. Drill-down capability is provided.
Figure 2-13 API dashboard
•API statistics
API statistics give a breakdown of calls by API and by HTTP operation. Drill-down capability is provided.
•Search and analyze
Search and analyze gives capability to search any of the data stored. This includes API usage, request and response headers, and the body content of the API request and response.
Logs and auditing
Auditing information is available from the Activity Feed menu item on the Getting Started menu. This gives information for the log of activity in API Manager (audit activity), API activity, and any system alerts. An example is shown in Figure 2-14 on page 33.
Figure 2-14 Activity feed showing audit and API activity and alerts
Debug information is provided in API activity and shows the request and response headers. Alerts show system alerts, such as connectivity failures.
Application developers
A view of the registered developers is available. Here you can contact them through email, view their API calls, and block them from making any API calls.
2.5 Introducing the use case scenario and user roles
This book shows how to build an API in the context of a scenario. The use case is for Redbooks Fictional JKHLE Airways, that wants to expose travel information about its services. The initial solution includes the documentation and definition of APIs to access passenger information, and flight and baggage status. This information can then be used by travel companies that use this airline. In our scenario, the fictitious travel company is called IBM Redbooks Fictional Travel Company (TheTravelCompany).
In building this scenario, the focus is on how IBM Management is used to create and expose the API:
•It is assumed the JKHLE baggage handling and other system services are already implemented, tested, and available.
•Application development best practices to enable API Management are not addressed.
The JKHLE architecture team produces an enterprise vision for implementing IBM API Management. The IT operation team works with the JKHLE architecture team to deploy the product according to their vision.
2.5.1 Storyboard
As a result of JKHLE Airways exposing its information, TheTravelCompany builds a travel portal and mobile application for its customers. How JKHLE builds its API and how TheTravelCompany uses that API is the purpose of the scenario.
The scenario storyboard is as follows:
1. A customer signs up to the TheTravelCompany portal to use the consolidated booking and travel management system the site offers.
2. During sign-up, customer is asked whether to incorporate the customer’s JKHLE passenger information in the portal, including the status of booked flights and baggage transfer.
3. An OAuth 2.0 flow takes place that grants an access token to TheTravelCompany that allows access to the JKHLE passenger information of the customer.
4. During the course of the flow, the customer authorizes TheTravelCompany to access JKHLE passenger information by entering the JKHLE user name and password.
5. The customer checks in online for a JKHLE flight using the TheTravelCompany portal.
6. The access token granted to TheTravelCompany has an lifetime of one month:
 – If the TheTravelCompany portal accessed the customer’s JKHLE passenger profile within one month, the access token granted at sign-up will be valid.
 – If the TheTravelCompany portal does not access the JKHLE API for more than one month, the customer must re-authenticate with the JKHLE user name and password, and an access token will be renewed.
7. The customer takes flight and arrives at the destination. The customer uses the TheTravelCompany mobile app to track baggage status.
8. The TheTravelCompany mobile app uses the same access token granted through the portal to retrieve passenger baggage status and requires the customer to re-authenticate.
9. The baggage status is returned to the customer, indicating that it is delayed and will arrive on a later flight.
10. The customer can use the mobile app to request delivery of baggage. This invokes the JKHLE API to add a baggage delivery address to the passenger profile for the flight.
This application flow is shown in Figure 2-15.
Figure 2-15 Use case story flow
The following chapters describe each aspect outlined in this overview and use this scenario to show how an API can be implemented. Chapter 3, “Defining APIs” on page 37 and Chapter 4, “Entitlements” on page 71 develop the API resources and set entitlements; Chapter 9, “Developer Portal” on page 189 provides the example of how an application developer gains access and use the APIs.
2.5.2 User roles, fictitious names, and their responsibilities
Table 2-1 lists typical user roles and their responsibilities that are related to API Management. To compliment the use case scenario introduced in this chapter, we also provide fictitious user names associated with the roles. These users are involved in constructing the baggage handling API system.
Table 2-1 User roles, fictitious names, and their responsibilities
Role
Name
Responsibility
API Administrator
Bob
Configuring and managing the product; managing API Authors; customizing the Developer Portal; setting up and adjusting entitlements. There may be a single API Administrator role (but it might be filled by multiple personnel).
API Developer
(API Publisher)
Shavon
Creating, testing and publishing APIs. There are likely to be many API Developers.
Application Developer
(API Consumer)
Andre
Building applications from exposed APIs. For the use case, Andre built mobile apps that call the JKHLE API.
Application User
Alice
Using the applications built by the application developers. In the use case, Alice uses the mobile app that calls the JKHLE API.
API Product Manager
Steve
Works with API Administrator and API Developers to established entitlements based on the defined business model. Responsible for marketing and socializing APIs, approving application developers requests for consumption, and using the analytics produced by the product to evaluate performance and make investment decisions.
IT Operations
Will
Installation and management of the product.
 
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.217.211.92