Introduction to Cast Iron Live Web API Services

Web APIs are a new and fast-growing business channel that is helping companies connect with the outside market and deliver services and products efficiently. This article shows you how to create, socialize, and manage your web APIs, by using IBM Cast Iron Live Web API Services.

Tanmayee Potluri (tpotlur@us.ibm.com), Product Manager, Cloud Integration, IBM

Photo of Tanmayee PotluriTanmayee Potluri is a product line manager for cloud integration on the Cast Iron team. She works on IBM API Management and is responsible for handling any product management issues related to the product. Tanmayee joined IBM in 2012 and holds a Master of Science degree in Computer Science from San Jose State University.



Simon Dickerson (simon.dickerson@uk.ibm.com), WebSphere Technical Sales for Connectivity/Mobility, IBM

Photo of Simon DickersonSimon Dickerson is an IBM technical pre-sales consultant in the UK and Ireland, working with the Cast Iron products and Mobile Foundation. He has served in a variety of IT roles including training, support, and consulting, and has been focused on technical sales for over 10 years. He has expertise in a number of application areas including content management and document security, mobile applications, and data quality on a variety of platforms and across many industries. Simon holds a degree in Cybernetics and Control Engineering with Mathematics from the University of Reading.



21 March 2013

Introduction

Try it!

Sign up for a free, 90-day cloud-hosted trial of Cast Iron Live Web API Services.

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
Image showing the 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
Image showing an overview of the 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
Image showing 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
Image showing the 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 (optional)

DataPower appliances simplify, govern, and optimize the delivery of services and applications and enhance the security of XML and IT services. They extend the capabilities of an infrastructure by providing a multitude of functions. The capabilities of DataPower appliances have increased from the core business of SOA connectivity to business-to-business connectivity and web application proxying. The DataPower appliances also support Web 2.0 integration with JavaScript Object Notation (JSON) and Representational State Transfer, advanced application caching, rapid integration with cloud-based systems, and more. These appliances offer a pragmatic approach to security, integration, and intelligent application delivery as purpose-built, easy-to-consume, and easy-to-use products with reduced costs.

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
  • OAuth
  • Authentication
  • Secure Sockets Layer termination
Figure 5. Cast Iron Live Web API Services with DataPower
Image showing 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
Image showing 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.

Specifying resources

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 DELETE, GET, PUT, or POST method 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
Image showing how to assemble 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
Image showing the 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
Image showing how to map 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
Image showing how to define 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 shown.

Figure 11. Testing your API
Image showing how to test 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
Image showing how to select layout and text to customize the portal

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
Image showing how to add social networking information to the portal

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
Image showing 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
Image showing 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
    Image showing how to explore 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.

Adding documentation

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
Image showing how to 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
Image showing 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
Image showing 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
Image showing 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
Image showing how to 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
Image showing how to manage app developers

Conclusion

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.

Acknowledgment

We would like to thank Laura Olson for encouraging and guiding us in writing this article.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Mobile development, Web development
ArticleID=862214
ArticleTitle=Introduction to Cast Iron Live Web API Services
publish-date=03212013