Companies need an efficient way to deliver services and products in order to connect with the outside market. Web APIs can help you reach a new generation of devices and customers, respond to competitive pressure, stay connected with partners and the outside world, keep pace with the rate of application change, and cultivate brand loyalty.
A web API is a public persona for a company, exposing defined assets, data, or services for public consumption. An API can provide a hook for colleagues, partners, or third-party developers to access data and services to build both web applications and mobile applications quickly. An app developer can leverage a web API with ease and invoke it via a web browser, mobile application, or device. Product catalogs, phone listings, insurance cases, order status, and bank loan rates are a few of the services exposed via APIs.
A web API extends a company and helps it engage with the outside market by opening new channels and allowing external app developers to easily leverage, publicize, and aggregate a company's assets for broad-based consumption. The growth of APIs has been tremendous in the past few years, and many companies claim that they get more traffic through their APIs than through their websites. Some APIs are open to any developer, some are open only to partners, and some are used internally to help run the business better and facilitate collaboration among teams. Examples of such APIs include the Facebook API, Twitter API, Netflix API, and Yellow Pages API.
The goals of a web API include supporting diverse platforms, driving innovation in the industry, and deriving primary and supplementary value from other APIs. To make an API successful, companies must reduce the entry barrier, make it developer-centric, and use existing technology wherever possible. However, companies may also need to control the amount of traffic an API accepts, in order to monetize the API by charging for additional traffic, discourage or prevent abuse of the API, and keep track of customer data usage, for example.
Web APIs face various challenges, making API management necessary. API management has many benefits and can help a company further develop its business. For example, effective API management can help control API access, support numerous application developers, and enable data analytics to gauge the success of the API.
Overview of Cast Iron Live Web API Services
IBM® WebSphere® Cast Iron Live Web API Services expands on service-oriented architecture (SOA). It provides end-to-end governance and control from within the company and extends it out into the API economy. The reference architecture shown in Figure 1 consists of several key domains:
- The API builder. This domain refers to the tools that enable the API developer to easily create and configure an API, define its limits and access controls, manage developers, and customize the developer portal with which they interact.
- The developer portal. A critical part of the API strategy, the developer portal enables the API developer to reach the developer community.
- The API gateway. This domain is responsible for handling access control to the API, managing entitlements and service levels, and providing threat protection.
- Analytics. The analytics domain is responsible for delivering both technical and operational metrics as well as business analytics and custom business reporting.
- On-premise WebSphere DataPower® demilitarized zone gateway. This gateway exposes services and credential stores behind the firewall.
- On-premise WebSphere Service Registry and Repository (WSRR). This tool provides API and enterprise service life-cycle management.
Figure 1. Reference architecture
The sections that follow provide a brief introduction to three of the important domains of the reference architecture. DataPower and WSRR are optional components of the solution described in this article.
Cast Iron Web API Services
DataPower, WSRR, and Cast Iron Live Web API Services help a company become more engaged with its market. Cast Iron Live Web API Services is a Software as a Service (SAAS) offering that enables companies to create new web APIs with existing assets, socialize web APIs in various communities to increase traffic, and manage web APIs. The capability for organizations to extend their presence while maintaining business control and insight makes Cast Iron Live Web API Services an effective place to develop and publish web APIs to expose the organization's assets and services.
The Cast Iron Live Web API Services solution is easy and simple to use because of its "configuration, not coding" approach. Someone with minimal programming skills can use the solution with ease. Using the Cast Iron Live Web API Services platform, you can create completely new APIs from scratch or extend existing APIs. You can get complete analytics on developers, applications, and use of the APIs. The solution also provides a developer portal to help developers collaborate and share when using the APIs. Figure 2 provides an overview of the solution.
Figure 2. Overview of Cast Iron Live Web API Services
IBM's API solution provides a robust mechanism for exposing resources and synchronizing them with the back-end data needed in those resources. This synchronization can be achieved through a simple proxy to an existing service or through the assembly of existing applications and data to create the appropriate actions and responses.
The simple, easy-to-use developer interface and tooling help make applications and services available to a community of web developers and partners via additional web APIs. A web API typically consists of a request and a response made over HTTP. The templates for different data sources that Cast Iron Live Web API Services provides allow you to easily identify what parts of an application or service will be accessible via the web API.
The key features and benefits of IBM's solution include:
- Up and running in minutes. The easy-to-use user interface and configuration capabilities mean that you can start reaping the benefits of the solutions almost immediately.
- Proxy to existing services. This is a key feature in leveraging the existing IT estate.
- Rapidly assemble new APIs. Rapidly create new APIs from existing systems and applications, following a "configuration, not coding" approach.
- Documentation of APIs. The documentation allows developers to be self-sufficient yet creative in how they use the content.
- Full analytics. Organizations can actively monitor usage and patterns, gaining valuable insight into how the service is running and how best to manage it in the long term.
- Rate limiting of APIs through entitlements. Ensure a controlled and secure service.
- Developer portal. This portal gives developers a community to share and collaborate in when using the APIs.
- Caching and flood control. Protecting back-end systems from the impact of a multitude of applications and devices requires caching to support common and repeatable queries and flood control. This is an embedded and key part of IBM's web API solution.
The Cast Iron Live Web API Services home page (see Figure 3) appears after you register for the services and log in. The three major components of the Cast Iron Web API Services are Create, Manage, and Socialize.
Figure 3. The Cast Iron Live Web API Services home page
Each of these service areas is described in detail in the rest of this article. Figure 4 shows what each of component provides. Also, it shows how the solution benefits the three key actors of the API economy: the IT professional, the external app developer, and the business user.
Figure 4. Three actors of the API economy and the benefits that the solution offers to each
WebSphere Service Registry and Repository (optional)
WSRR is an enterprise service catalog that manages all the services and APIs the enterprise has, as well as the life cycle. Some of the services and APIs in this catalog can be exposed externally through the Web API Services solution. Today, this is a manual process of moving metadata between the two. Ultimately, WSRR is the single point of reference for all services and APIs an enterprise owns, some of which are exposed externally through Cast Iron Live Web API Services.
DataPower appliances secure the web APIs at the edge of the enterprise (see Figure 5). They also secure the borders of the enterprise, while WSRR provides an enterprise view and governance control over all the services in it. WSRR manages the run time policies applied to the services that DataPower or other enforcement points then consume.
The Cast Iron Live Web API Services, along with DataPower, provide hardened security in addition to rapid on-ramping of web APIs. DataPower is required to get fine-grained authorization (OAuth) working with The various features that DataPower provides include:
- XML firewall
- Service virtualization
- Secure Sockets Layer termination
Figure 5. Cast Iron Live Web API Services with DataPower
Create your web API
This section provides details about the Create component of the Cast Iron Live Web API Services. Using this component, you can define, implement, secure, scale, and test an API.
Define the API
You first define an API by creating the API with a name and description, and then specifying the resources it will use. You then either implement the API as a proxy to an existing service or create it using Cast Iron Live Web API Services. You can invite other people (API authors) to help create and define the API.
When an API is created, it is defined as private by default. To list the API in your organization's web API store, edit the API to change its visibility to public. The definition of the API includes a description, which is used as part of the documentation provided to developers (see Figure 6).
Figure 6. The Define APIs and Resources page
Adding an author
To add an author, provide the name and email address of the person. The people you invite receive a note that includes a link that guides them through the sign-up process. The first time they sign in, the license agreement is displayed. The invited author must click Accept to complete the sign-in process.
An API is a collection of resources, where resources
represents the operations or methods you want to expose in the API. The
API resources that application developers use are defined following the
HTTP and web style of interactions (an HTTP
must be selected). As the API and resources are defined, the information
provided around descriptions, input and output data, and service level are
used to automatically generate the API documentation.
Assemble the resource using a simple proxy
The resource can be a proxy (for which you enter the URL for the server you want to forward the request to), or you can implement a new resource (see Figure 7). By default, it is assumed that the proxy server handles JSON. When you call an API resource that returns XML, the output is UTF-8 encoded. Instance data pasted in the request, and response body section serves as a good example in the developer documentation. The type of instance data pasted in the request or response body determines whether the resource handles XML or JSON payloads. This data is also used to infer the object structure used in the assemblies, when needed.
Figure 7. Assembling the resource using a simple proxy
You can add, edit, and activate several resources for a single API: There is no limit. You can define separate resources to retrieve a single entity or many entities. Rather than requiring detailed schemas, for the request and response body, you enter a sample of the data, which helps with the speed and simplicity of creation and in understanding the API.
Assembling the resource by connecting to a data source
If you are not defining a proxy to an existing web resource, you can create a new resource using a configuration approach to integrate with existing endpoints—for example, databases, HTTP-based services, salesforce.com, or an FTP server.
Connection to the resource
You first define a connection to the data source. If you are behind a firewall, you reach this source through the installation of a secure connector. The secure connector is defined, downloaded from the Cast Iron Live Web API, and installed to either a Windows or Linux operating system. The secure connector makes an outbound connection to Cast Iron Live Web API Services.
You can download the secure connector installation file and your configuration file from within the Web API design environment. The configuration file contains certain pieces of information needed to set up a secure tunnel and conversation with your applications and systems. Examples of the parameters in the configuration file include name, tenant ID, environment ID, cloud gateway, listen-on port, transmit-on port, and authorization key. You can also define resources not located behind a firewall. When defining the request, you specify the endpoint type to connect to. Figure 8 shows some of the endpoints available.
Figure 8. Available endpoints
Here, it is possible to add more than one request, which makes the aggregation of data from more than one data source available as a single API. For each request, you then define the connection (which may or may not use a secure connector).
Defining the resource
After a connection has been made, you can define the request and response headers, or — in many instances — a discovery will automatically be made. You can define a response by mapping and transforming values, as required, using drag-and-drop functionality (see Figure 9). No coding is required.
Figure 9. Mapping values
Secure the API
You can make an API secure and scale it using the entitlements feature (see Figure 10). For each web API, you can define up to three API entitlement levels, defining levels of usage and pricing. The description will be seen only by those people signing up to your store, and you can choose the level of security (ID, secret, or both) required and a limit on the number of calls that can be made in a given time period. An approval mechanism is also available, which allows you to specify entitlement levels that require your approval before a developer can be activated at that level. A simple task list mechanism helps you manage all approvals. The approval mechanism allows you to apply governance and checks on your developers before giving them access to a higher tier.
Figure 10. Defining entitlements
Test the API
You can make a simple test of the API from the definition page (see Figure 11). This page enables you to set values for
each test field (for example, if you selected the
GET method, you can enter values for the
parameters, request headers, and request body). The response will be
Figure 11. Testing your API
Socialize your web API
Cast Iron Live Web API Services helps your organization socialize its APIs using a branded developer portal. You can customize the web pages of your account portal to reflect your company's business. These pages will be seen by external users; they publicize your company and are key in creating new business opportunities. The branded developer portal encourages the quick exploration of the API, and provides easy developer sign-ups, featured developer apps, and details on how to hook into social communities. The portal also enables developers to manage their applications.
Branded developer portal
You customize the developer portal by selecting a layout and uploading your company logo and text (see Figure 12).
Figure 12. Selection of layout and text
You can also specify and include social networking and marketing information (see Figure 13). You can specify the terms and conditions and other support and business constraint information around the use of the API. An API is published by the simple process of activating it, and then making it public.
Figure 13. Adding social networking information
When developers have completed their application, they can request that it be featured on your company portal. This request management is built into Cast Iron Live Web API Services, as shown in Figure 14.
Figure 14. A customized developer portal
Manage and test applications
When the APIs are ready, the developer must sign up to your API store to access your APIs. After accepting the terms and conditions, the developer can see the available APIs, register his or her application, select entitlements, and test the application. Signing up for the API requires a company name, user name, and password (given through an activation email). The developer then accesses the web APIs though a URL in the following format:
https://<company portal name>.developer.castiron.com/webapi/
The portal store is shown in Figure 15.
Figure 15. Getting started with the portal store
From the portal store, the developer can:
- Browse to see the available company web APIs (see Figure 16);
Figure 16. Exploring an API in the store
- Register applications that are going to use one or more web APIs, and select the appropriate web API entitlement levels
- Manage their applications and web API usage
An application must be registered before any API can be used, and a unique app ID and secret must be created. When developers sign up to use the APIs, they can register applications and manage the use of the APIs.
Manage your web API
The Manage component of the Cast Iron Live Web API Services is used for analyzing the traffic of the API, managing application developers, and managing the web API's external presence.
You can also upload additional documentation, like code samples and guide docs, for the API. From the location shown in Figure 17, you can add documentation and descriptions for all parameters, enter the headers, and upload additional documentation.
Figure 17. Add documentation for the API
Analyzing API traffic
Web APIs become a product of an organization's business and hence require product management. Companies need to understand the web API uses and should be able to control their growth and improve adoption. They also need insights into the communities in which their web APIs are being used.
The Cast Iron Live Web API Services solution helps you understand the five Ws of web APIs: what, where, who, when, and why. It provides detailed analytics of web APIs over various periods of time as well as details on the traffic across all APIs, an understanding of which mobile device invoked the web APIs, top traffic-producing web applications, and information about which geolocation is producing the most traffic (see Figure 18).
Figure 18. Business analytics
Using Cast Iron Live Web API Services, an organization can manage its web APIs with business-level controls. The solution provides the ability to define service levels for individual APIs as well as visualize and search through business analytics for both application developers and API providers (see Figure 19).
Figure 19. Structured filtered search across analytics for APIs and apps
IBM's solution helps you to define service levels for the API, as shown in Figure 20.
Figure 20. Service levels for APIs
You can also self-document APIs as well as add samples and metadata, control the APIs available on the developer portal, and manage API users, as shown in Figure 21.
Figure 21. Manage API users
Manage application developers
You can manage the application developers who are using the API through the Cast Iron Live Web API Services solution. You can approve requests sent by developers, send emails to developers, block a particular developer, and view a developer's usage, as shown in Figure 22.
Figure 22. Manage application developers
Cast Iron Live Web API Services provides a strong platform for creating APIs and showcasing them through a branded developer portal. It helps you develop your business and reach out to the market and your business partners. It not only helps you build APIs but also helps you manage the APIs and improve your business.
The power of DataPower, WSRR, and Cast Iron Live Web API Services together makes it possible for an enterprise to grow its business and become an engaging enterprise.
A free 90-day trial is available for Cast Iron Live Web API Services (see Resources for a link). All the features are available in this trial. Explore the world of APIs with IBM's web API solution.
We would like to thank Laura Olson for encouraging and guiding us in writing this article.
- Free trial
- Cast Iron Live Web API
Get a free 90-day trial.
- Cast Iron Live Web API Services
- WebSphere Cast Iron resources
- WebSphere Cast Iron V6.1 information center
Guidance on the key tasks required to use WebSphere Cast Iron Version 6.1.
- WebSphere Cast Iron Studio information center
A single Web portal to all WebSphere Cast Iron Cloud Integration documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere Partner Gateway.
- WebSphere DataPower Cast Iron Management API guide
Information on the Management API for the Cloud and Integration Appliances.
- WebSphere Cast Iron Cloud Integration product library
Product announcements, case studies, white papers, and more.
- WebSphere Cast Iron Cloud Integration product page
Product descriptions, product news, training information, support information, and more.
- WebSphere Cast Iron Cloud Integration support
A portal for support problems and their solutions, plus downloads, fixes, problem tracking, and more.
- Cast Iron community forums
Get answers to your technical questions and share your expertise with other WebSphere Cast Iron users.
- IBM Software Services for WebSphere Cast Iron cloud
Rapidly deploy cloud, on-premise, or hybrid applications with help from IBM Software Services for WebSphere. Our team of Cast Iron cloud integration experts has deep technical skills and experience from thousands of customer integrations.
- IBM Redbook: Getting started with IBM WebSphere Cast Iron
Detailed introduction to the development and administrative interfaces for WebSphere Cast Iron.
Redpaper: Strategic Overview of WebSphere Appliances
Summary of the WebSphere appliances, including core functions and add-ons.
- Connect cloud and on-premise applications using IBM Cast Iron
This IBM Redguide for business leaders shows you how to use IBM Cast Iron OmniConnect to connect cloud and on-premise applications quickly and easily using "configure not code" cloud integration with built-in connectivity and integration templates.
- WebSphere Cast Iron V6.1 information center
- developerWorks resources
downloads for IBM software products
No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
business process management developer resources
BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
Join a conversation with developerWorks users and authors, and IBM editors and developers.
- developerWorks tech briefings
Free technical sessions by IBM experts to accelerate your learning curve and help you succeed in your most challenging software projects. Sessions range from one-hour virtual briefings to half-day and full-day live sessions in cities worldwide.
- developerWorks podcasts
Listen to interesting and offbeat interviews and discussions with software innovators.
- developerWorks on
Check out recent Twitter messages and URLs.
- IBM Education Assistant
A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.
- Trial downloads for IBM software products
Dig deeper into WebSphere on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.