Exposing and Managing Enterprise Services with IBM API

286 Pages·2014·5.36 MB·English

Front cover
IBM WebSphere
® ®
Exposing and Managing Enterprise Services
with IBM API Management
API concepts, business value,
and product overview
API creation, management,
developer portal, and more
API security, scalability,
analytics, and much more
Wei-Dong Zhu
Andrew J Daniel
Andrew A Das
Simon Dickerson
John Falkl
Katherine Sanders
Dinesh G Shetty
Chris Wood
ibm.com/redbooks

International Technical Support Organization
Exposing and Managing Enterprise Services with
IBM API Management
April 2014
SG24-8193-00
Note: Before using this information and the product it supports, read the information in
“Notices” on pageix.
First Edition (April 2014)
This edition applies to Version 2, Release 0, Modification 0 of IBM API Management (product
number D0ZSZLL).
© Copyright International Business Machines Corporation 2014. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi
Authors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi
Now you can become a published author, too! . . . . . . . . . . . . . . . . . . . . . . . .xiii
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
Stay connected to IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
Chapter 1. API concepts, trends, and overview. . . . . . . . . . . . . . . . . . . . . . 1
1.1 The world of APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 APIs and the traditional websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.1 API economy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.2 Various types of APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 The business of APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.1 Market pressure, competitive pressures, and business value . . . . . . 8
1.3.2 Evolution and growth of APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.3 Current trends across industries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.4 Need for APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.5 Considerations before launching APIs . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.6 Business strategies for APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.3.7 Business models for APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.4 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Chapter 2. IBM API Management introduction. . . . . . . . . . . . . . . . . . . . . . 15
2.1 Introduction to IBM API Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2 Deployment topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.1 Mobile enterprise application platforms. . . . . . . . . . . . . . . . . . . . . . . 17
2.2.2 Internal API exposure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2.3 External API exposure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3 API Management components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.4 IBM API Management solution overview. . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.4.1 Creating and managing APIs: Overview of the API Manager. . . . . . 22
2.4.2 API creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.4.3 Socializing APIs: An overview of the Developer Portal. . . . . . . . . . . 28
2.4.4 Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.5 Introducing the use case scenario and user roles. . . . . . . . . . . . . . . . . . . 33
2.5.1 Storyboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.5.2 User roles, fictitious names, and their responsibilities . . . . . . . . . . . 36
© Copyright IBM Corp. 2014. All rights reserved. iii
Chapter 3. Defining APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.1 Understanding API technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.1.1 Architectural decisions: REST and SOAP. . . . . . . . . . . . . . . . . . . . . 38
3.1.2 Encoding decisions: XML and JSON . . . . . . . . . . . . . . . . . . . . . . . . 40
3.2 Designing APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.2.1 Pragmatic REST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.2.2 Strict REST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.3 Defining APIs with IBM API Management 2.0. . . . . . . . . . . . . . . . . . . . . . 46
3.3.1 Creating an API definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.3.2 Adding resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.3.3 Testing the definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3.4 Scenario: Defining the JKHLE Airways API . . . . . . . . . . . . . . . . . . . . . . . 52
3.4.1 Creating the API definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.4.2 Creating the proxy definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.4.3 Creating the Assembly definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.4.4 Starting and testing the API definitions. . . . . . . . . . . . . . . . . . . . . . . 69
Chapter 4. Entitlements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
4.1 Overview of entitlements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4.2 Implementing entitlements in IBM API Management . . . . . . . . . . . . . . . . 72
4.2.1 Creating a local entitlement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
4.2.2 Creating a global entitlement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
4.3 Scenario: Defining the JKHLE Airways entitlements. . . . . . . . . . . . . . . . . 77
4.3.1 Creating the basic entitlement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
4.3.2 Creating the premium entitlement. . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Chapter 5. API security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.1 API security introduction and its importance. . . . . . . . . . . . . . . . . . . . . . . 82
5.2 Transmission encryption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
5.2.1 SSL certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
5.3 App ID and App Secret . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
5.4 Authenticating APIs and resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
5.4.1 Authenticating application users. . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.4.2 Nonauthenticated APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
5.4.3 Basic authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
5.4.4 OAuth protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
5.5 Securing an API in IBM API Management . . . . . . . . . . . . . . . . . . . . . . . . 91
5.5.1 Create an LDAP connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
5.5.2 Create an OAuth profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
5.5.3 Set up an Authentication URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
5.5.4 Securing the passenger profile API. . . . . . . . . . . . . . . . . . . . . . . . . . 95
5.5.5 Testing OAuth. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
iv Exposing and Managing Enterprise Services with IBM API Management
Chapter 6. Scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
6.2 Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
6.3 Capacity planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
6.3.1 Sizing the Management node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
6.3.2 Sizing the Analytics node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
6.3.3 Sizing the Gateway node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.3.4 Sizing the Assembly node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
6.4 API caching. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
6.5 Service level management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
6.5.1 Enforcing SLAs through Entitlements. . . . . . . . . . . . . . . . . . . . . . . 118
6.5.2 Capacity planning using Analytics. . . . . . . . . . . . . . . . . . . . . . . . . . 119
6.6 Cloud deployments for enterprise scale . . . . . . . . . . . . . . . . . . . . . . . . . 122
6.6.1 IBM PureApplication system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
6.6.2 IBM Workload Deployer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Chapter 7. Testing, debugging, and error handling. . . . . . . . . . . . . . . . . 125
7.1 Overview of API testing and debugging . . . . . . . . . . . . . . . . . . . . . . . . . 126
7.1.1 Testing APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
7.2 Testing APIs with IBM API Management 2.0 . . . . . . . . . . . . . . . . . . . . . 129
7.2.1 Testing in the API developer role (Shavon) . . . . . . . . . . . . . . . . . . 129
7.2.2 Testing in the application developer role (Andre) . . . . . . . . . . . . . . 133
7.3 Debugging APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
7.3.1 Debugging in IBM API Management 2.0 (Shavon's role) . . . . . . . . 135
7.3.2 Debugging in IBM API Management 2.0 (Bob's role) . . . . . . . . . . . 139
7.3.3 Advanced debugging techniques . . . . . . . . . . . . . . . . . . . . . . . . . . 142
7.3.4 Using monitoring, alerting, and postmortems . . . . . . . . . . . . . . . . . 148
7.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
7.4.1 Implementing Error Handling in IBM API Management 2.0 . . . . . . 152
Chapter 8. Versioning and promoting APIs . . . . . . . . . . . . . . . . . . . . . . . 155
8.1 Versioning APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
8.1.1 Minor versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
8.1.2 Major versions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
8.2 Promoting APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
8.2.1 Exporting APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
8.2.2 Importing APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
8.2.3 Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
8.3 Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
8.4 Scenario: Versioning and promoting the JKHLE Airways API. . . . . . . . . 162
8.4.1 Creating a major version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
8.4.2 Updating and unit testing the GET profile resource . . . . . . . . . . . . 164
8.4.3 Promoting the GET profile resource changes to test . . . . . . . . . . . 167
Contents v
8.4.4 Updating and unit testing the GET profile resource in test . . . . . . . 169
8.4.5 Creating and unit testing the PUT profile resource. . . . . . . . . . . . . 171
8.4.6 Promoting the PUT profile resource to test. . . . . . . . . . . . . . . . . . . 182
8.4.7 Reverting to Version 2.1 in test. . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
8.4.8 Updating and unit testing the PUT profile resource in test . . . . . . . 186
8.4.9 Promoting the new version to production . . . . . . . . . . . . . . . . . . . . 188
Chapter 9. Developer Portal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
9.1 Introduction to API Management Developer Portal. . . . . . . . . . . . . . . . . 190
9.2 Configuring the Developer Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
9.2.1 Accessing the configuration page. . . . . . . . . . . . . . . . . . . . . . . . . . 190
9.2.2 Customizing the home page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
9.2.3 Configuring the Sign Up Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
9.3 Registration, sign in, and details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
9.3.1 Sign In. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
9.3.2 Profile settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
9.4 API documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
9.5 Registering an application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
9.6 Using entitlements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
9.6.1 Selecting an entitlement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
9.7 Testing and using APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
9.8 Measuring your API usage: the Dashboard . . . . . . . . . . . . . . . . . . . . . . 209
9.9 Developing the scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
9.9.1 Registration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
9.9.2 Registering an application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
9.9.3 Selecting API entitlements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
9.9.4 Testing an API resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Chapter 10. Analytics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
10.1 Introduction to analytics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
10.2 API product manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
10.2.1 Top five APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
10.2.2 API calls and response time statistics. . . . . . . . . . . . . . . . . . . . . . 223
10.2.3 Search and deep analysis on API calls. . . . . . . . . . . . . . . . . . . . . 224
10.3 IT operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
10.3.1 Monitor health of the environment. . . . . . . . . . . . . . . . . . . . . . . . . 230
10.3.2 View information about activities. . . . . . . . . . . . . . . . . . . . . . . . . . 243
10.4 API developer (publisher) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
10.4.1 Audit Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
10.4.2 API Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
10.4.3 Alerts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
10.5 Application developer (consumer). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
10.5.1 Dashboard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
vi Exposing and Managing Enterprise Services with IBM API Management
Chapter 11. Mobile app development . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
11.1 API Management and mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
11.2 IBM MobileFirst. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
11.3 IBM Worklight for mobile application development. . . . . . . . . . . . . . . . 255
11.3.1 Worklight component overview. . . . . . . . . . . . . . . . . . . . . . . . . . . 256
11.4 Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
11.4.1 Internal and external APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
11.5 Integration and Worklight adapters. . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
11.6 Using REST APIs in building an app. . . . . . . . . . . . . . . . . . . . . . . . . . . 260
11.6.1 Benefits of an API assembly and API optimization. . . . . . . . . . . . 261
Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
System requirements for downloading the Web material . . . . . . . . . . . . . 264
Downloading and extracting the Web material . . . . . . . . . . . . . . . . . . . . . 264
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Contents vii
viii Exposing and Managing Enterprise Services with IBM API Management