Digital acceleration

Making your services available on the Web

Companies today want to make their backend services available on the web so that these services can be consumed by apps running on mobile devices and desktops. A company might want to expose services that provide product pricing and availability information, sales and ordering services, order tracking services, and any other services required by client apps.

Companies often expose services as a set of HTTP endpoints. Client app developers then make HTTP requests to these endpoints. Depending on the endpoint, the service might then return data, formatted as XML or JSON, back to the client app.

The client apps that consume these services can be implemented as standalone apps for a mobile device or tablet, as HTML5 apps running in a browser, or as any other type of app that can make a request to an HTTP endpoint and consume any response data. These apps might be developed and released by the same company that exposed the services, or by third-party app developers who make use of publicly available services.

The following image shows this type of model:

Because providers make their services available over the web, they must ensure that they have taken all necessary steps to secure and protect their services from unauthorized access. As a service provider, consider:

Security - How will you control access to your services to prevent unauthorized access?

Compatibility - Will your services work across different platforms and devices?

Measurability - How can you monitor your services to make sure they are available?

Monetization - How can you track and bill customers for access to your services?

And many other considerations

After a client app has been released that accesses any services, the service provider is then required to make sure that those services continue to work over time as they add, modify, or delete those services. The service provider must also have a way to keep app developers aware of any changes to the services to ensure that client apps stay in sync with those services.

Client app developers face challenges when trying to consume services from different providers. There are many technologies available today for use by a service provider to expose its services. The same client app might have to use one mechanism to consume a service from one provider, and a different mechanism to consume a service from a different provider. App developers can even face the situation where they have to use different mechanisms to consume services from the same provider.

Making services available through Apigee Edge

Apigee Edge, which is built on Java, enables you to provide secure access to your services with a well-defined API that is consistent across all of your services, regardless of service implementation. A consistent API:

Makes it easy for app developers to consume your services.

Enables you to change the backend service implementation without affecting the public API.

Enables you to take advantage of the analytics, monetization, developer portal, and other features built into Edge.

The following image shows an architecture with Edge handling the requests from client apps to your backend services:

Rather than having app developers consume your services directly, they access an API proxy created on Edge. The API proxy functions as a mapping of a publicly available HTTP endpoint to your backend service. By creating an API proxy you let Edge handle the security and authorization tasks required to protect your services, as well as to analyze, monitor, and monetize those services.

Because app developers make HTTP requests to an API proxy, rather than directly to your services, developers do not need to know anything about the implementation of your services. All the developer needs to know is:

The URL of the API proxy endpoint.

Any query parameters, headers, or body parameters passed in a request.

Any required authentication and authorization credentials.

The format of the response, including the response data format, such as XML or JSON.

The API proxy isolates the app developer from your backend service. Therefore you are free to change the service implementation as long as the public API remains consistent. For example, you can change a database implementation, move your services to a new host, or make any other changes to the service implementation. By maintaining a consistent frontend API, existing client apps will continue to work regardless of changes on the backend.

You can use policies on the API proxy to add functionality to a service without having to make any changes to the backend service. For example, you can add policies to your proxy to perform data transformations and filtering, add security, execute conditional logic or custom code, and to perform many other actions. The important thing to remember is you implement policies on Edge, not on your backend server.

Creating an API product in Apigee Edge

An API proxy is the HTTP endpoint on Apigee Edge that developers use to access your backend services. While it is possible, you typically do not make individual API proxies available. Instead, you group one or more API proxies into an API product.

An API product is a bundle of API proxies combined with a service plan. That service plan can set access limits on API proxies, provide security, allow monitoring and analytics, and provide additional features. API products are also the central mechanism that Edge uses for authorization and access control to your APIs.

You have a great deal of flexibility when creating API products. For example, multiple API products can share the same API proxy. The following figure shows three API products. Notice that all products allow access to API proxy 3, but only product A allows access to API proxy 1.

You can set different properties on each API product. For example, you might make available one API product with a low access limit, such as 1000 requests per day, for a bargain price. You then release another API product that provides access to the same API proxy, but with a much higher access limit, for a higher price. Or, you might create a free API product that allows read-only access to your services, and then sell an API product to the same API proxies that allows read/write access.

Allowing a client-side app to access your API product

When app developers decide that they want to access your services, they must first register their client app with your API product. Upon registration, an app developer receives an API key that she must then include in every request to an API proxy included in the API product. That key is authenticated and, if authentication is successful, the request is allowed to access your backend service.

At any time, you can revoke the key so that the client app no longer has access to your services. Or, you can define a time limit on a key so that the developer must refresh the key after a specific time.

You decide how to handle registration requests from developers to access your API products. By using Apigee Edge Developer Services, you can automate the registration process; or you can use a manual process to control access.

Steps to create API products and making them available to developers

Create one or more API proxies that map publicly available URLs to your backend services.

Create an API product that bundles your API proxies.

Deploy your API proxies and API product.

Let your developers know that the API product is available.

Once app developers know about the availability of your API product, they:

Register their client apps with your API product.

Receive an API key for the API product.

Make requests to your services through API proxies (which are bundled in the API product) and pass the API key with each request.

Components of Apigee Edge

Apigee Edge consists of the API, Analytics, and Developer Services that together provide a comprehensive infrastructure for API creation, security, management, and operations, as well as powerful backend services for developing client apps.

The following figure shows Edge services:

Edge API Services

Apigee Edge API Services are all about creating and consuming APIs, whether you're building API proxies as a service provider or using APIs, SDKs, and other convenience services as an app developer.

On the API-building side, the API management server provides tools for adding and configuring your API proxies, setting up API products, and managing app developers and client apps. It offloads many common management concerns from your backend services. When you add an API proxy, you can apply policies to the API proxy for adding security, rate-limiting, mediation, caching, and so on. You can also customize the behavior of your API proxy by applying custom scripts, making calls out to third-party APIs and services, and so on. See Understanding APIs and API proxies for more.

On the API-consuming side, API Services powers mobile and Web apps by giving app developers access to a flexible data store and to key features such as social graphs, geolocation, user management, push notifications, performance monitoring, and more. These features, available with SDKs for iOS, Android, JavaScript, and others, let app developers focus on creating the rich features and user experience that truly differentiate a client app rather than burning time implementing core backend services and infrastructure. See API BaaS features for more.

If you're a node.js developer, you can seamlessly add your node.js modules to Edge to create APIs and API mashups, all the while leveraging the benefits Edge provides, from message transformation to security to analytics.

Edge Analytics Services

Apigee Edge Analytics Services provides powerful tools to see short- and long-term usage trends of your APIs. You can segment your audience by top developers and apps, understand usage by API method to know where to invest, and create custom reports on business- or operational-level information.

As data passes through Edge, several default types of information are collected including URL, IP, user ID for API call information, latency, error data, and so on. You can create policies to add other information, such as headers, query parameters, and portions of a request or response extracted from XML or JSON. This information is collected asynchronously from the actual request/response flow and therefore has no effect on API performance.

The management UI lets you perform most analytics management tasks in a browser, as shown in the following figure:

However, you can also access and control the Analytics Service by a command-line interface or through RESTful APIs. See Analytics Services overview for more.

Edge Developer Services

Apigee Edge Developer Services provide the tools to manage the community of app developers using your services. Developer Services offers the flexibility to work with internal and external developers and formalize these relationships with financial models.

Developer Services provides the ability to onboard developers and create a developer portal for your publicly available API products. App developers connect to your portal to access API documentation, forums, and a blog. Every Edge customer can create their own developer portal, either in the cloud or on-premises with Apigee Edge for Private Cloud. The following figure shows the home page of the default developer portal:

Monetization capabilities provide the financial infrastructure and relationships to turn your Developer community into an actual channel for your digital assets. With monetization, you can create a variety of rate plans that charge developers for the use of your API products or let you pay developers in revenue-sharing scenarios. Plans include pre-paid plans, post-paid plans, fixed-fee plans, variable rate plans, "freemium" plans, plans tailored to specific developers, plans covering groups of developers, and more. In addition, monetization includes reporting and billing facilities. See The basics of monetization for more.

The difference between Edge in the cloud and on-premises

You can install Edge on-premises (Apigee Edge for Private Cloud) in your own environment to retain complete control of the environment and of the deployment taxonomies. Alternatively, you can use the cloud-hosted (SaaS) version where Apigee is responsible for maintaining the cloud environment for you, allowing you to concentrate on building your services and defining the API to those services.

The functionality between the two versions is virtually identical. The difference is that the cloud supports both free and paid accounts, and that the hardware and software environment is managed by Apigee. With an on-premises installation, which requires a paid account, you are in complete control of Edge installation and deployment. To fully support an on-premises installation, Edge includes components such as the Apigee management server, an Apache Cassandra NoSQL database, an ApacheDS LDAP server, a message router, and a message processor.

Developing with Apigee Edge

Two different audiences make use of Apigee Edge and its services:

Service providers who create API Proxies and API products to expose backend services.

App developers who consume these API proxies and API products to create apps for mobile and desktop devices. Client app developers also use API Services for data persistence and management, as well as features such as geolocation and push notifications.

Edge provides tools to support both types of audiences.

API proxy and API product development

As a service provider, you can use two different development methods to create, configure, and maintain API proxies and API products:

Make HTTP requests to the Apigee RESTful APIs to access Edge services.

Using the RESTful management API

All Edge services can be configured through a set of RESTful APIs. That means you can use scripts to create, configure, and manage API proxies and API products, create and manage apps and app developers, and to perform many other types of operations. These endpoints often take data containing configuration information and require you to pass authentication information, such as username and password, to access them.

Following RESTful principles, you can call HTTP GET, POST, PUT, and DELETE methods on any of the API resources. The following example uses cURL to execute an HTTP POST request to create an API product:

Using the management UI

The Edge management UI provides browser-based tooling that lets you perform most of the tasks necessary to create, configure, and manage API proxies and API products. There are still a few tasks that require you to use the RESTful API, though.

The following image shows the Edge management UI that you can use to create and configure an API proxy:

Client app development

App developers access your services by making HTTP requests to API proxies. There are no requirements on the type of client app, other than making a properly formatted HTTP request and handling any data returned by the response.

If client app developers want to take advantage of the app-building features included with Edge API Services, their apps can either make HTTP requests directly to those services or use one of the Apigee client SDKs for Android, iOS, JavaScript, HTML5, and others.

Deployment environments

Every organization using Apigee Edge automatically has at least two environments they can use to develop, test, and deploy APIs: test and prod. Use the test environment to develop and test your APIs before making them publicly available. Only your internal developers can access APIs deployed to the test environment. Deploy your APIs to the prod environment to make them publicly available to app developers.

Debugging and testing

Edge API Services provides a trace tool that lets you debug end-to-end request and response flows. The trace results display request and response headers and payloads, policy execution, variable values, and any errors that may have occurred during the flow.

Key data points for use in troubleshooting:

Timestamps: Use timestamps to see how long each step takes to execute. Comparing timestamps helps you isolate the policies that are taking the longest to execute that are slowing down your API calls.

Base path: By verifying the base path, you can ensure that a policy is routing the message to correct server.

Results of policy execution: These results let you see if the message is being altered as expected, such as if the message is being transformed from XML to JSON, or if the message is being cached.

The following figure shows trace results:

Each Trace session is broken down into the following major steps:

Original request received from client: Displays the verb and URI path of the request from the client app, headers, body data, and query parameters.

Request sent to your backend service: Displays the request message sent to the backend service by the API proxy.

Response returned by the backend service: Displays the response headers and payload returned by the backend service.

Final response sent to client: The response message returned to the requesting client app once the response flow has executed.