At the Layer 7 API Academy, we’ve had a few requests from API designers who are seeking strategies for handling large amounts of data in API responses.  Pagination is the most common method for addressing this scenario. Pagination, which is very common on the Web, allows API architects to conserve resources, improve response times and optimize the user experience. It’s a way of splitting up data into “pages” and is used in just about any API that returns collections of data.

I’ve released a short video tutorial titled Use Pagination in Web API Design to introduce the ins and outs of the interface. This video provides a crash course explaining pagination and outlining how to use it effectively in the design of Web APIs. I couldn’t fit all the implementation considerations I wanted in this six-minute tutorial, so watch out for a follow-up video on the subject.

I’m happy to announce the release of the first API Academy video shorts. I’ve been working with my colleague Ronnie Mitra to create a series of short (five-minute), informative videos on topics related to the Web, APIs and solution design/implementation.

These first few videos are just the start. We plan on doing more of these shorts on a wide range of topics, over the coming weeks and months. And we need your help. Please take a look at these first vids and send us your feedback.

You can comment here, on YouTube or by emailing me directly. We’re looking for feedback on the format, suggested topics and even how we could improve upon this model (hosting a separate site, adding interaction, badges etc.)

Any time you can spend on watching these and sending comments will be most appreciated. Our aim is to do something helpful, engaging and – above all – enjoyable. Thanks for your help and let’s see what this can become!

The API Interaction Model – An Introduction

—

Three Common Web Architecture Styles

—

Handle Errors on the Web

Most of the time, even public APIs start off as private APIs – as part of their development lifecycle. Until an API has been fully tested and is ready to be launched, it remains private and only accessible to its internal developer base. The ability to “flick the switch” on an API, to make it jump from a staging mode to a live mode, is an essential feature of an API management infrastructure.

Then there are APIs that are never meant to be public in the first place. Most APIs actually fall under this category. Many enterprises that are moving forward with API management are exposing APIs privately – for example, to facilitate the creation of custom mobile apps for their employees, in order to tap into the BYOD trend. Those APIs are intended to be consumed by their own developers, contractors and sometimes partners.

The Layer 7 API Portal is geared towards managing APIs that are either public or private and lets API managers control which developers are made aware of which APIs. This lets you have a single point of management for all APIs, regardless of their target audience. By default, only public APIs are visible on the API Portal.

A series of tutorial videos for the API Portal product has recently been posted on our YouTube channel. As it happens, one of videos is called Publish a Private API and it’s embedded below.

We’ve previously provided some insight into the process of translating between REST and SOAP in a tutorial on our Web site. In that tutorial, we demonstrated how our policy language lends itself to a simple way of defining the conversion process, making converting REST to SOAP a fairly trivial exercise. However, if you have tens or hundreds of existing SOAP services, translating them all to REST might seem somewhat daunting.

Luckily, a Layer 7 Gateway can also help to make that process considerably easier – and I’m going to show you how. I’ll be walking you through a wizard that makes it simple to (a) upload your Web services to the Gateway as WSDLs and then (b) customize how you want the REST version of each service to look.

First, you upload your WSDL.

Then, configure how you would like to present your REST interface.

Each operation can be customized with the type of HTTP method used.

Once you submit your configuration, you’re ready to go!

At the end of the wizard, sample HTML-based documentation is provided that can be used for presenting the REST endpoint to your clients. This documentation is the first step in presenting the details of your new RESTful API via the Layer 7 API Portal.

Here’s an example of the same operation above that was converted to a HTTP GET style.

Finally, we also provide a sample WADL based on the parameters that you specify.

Once you login to the Layer7 Policy Manager, you’ll find a predefined policy that does all the conversion from REST to SOAP.

From here, you can add any additional policy enforcement requirements as you see fit.

At Layer 7, we’ve responded with the creation of our OAuth Toolkit, as well as a series of tutorial videos that explain how enterprises can use the Toolkit to simplify OAuth implementation. Now, in response to the overwhelmingly positive response we’ve received to these tutorials, we’ve decided to give them their own section on our Web site.

This section features all of Francois Lascelles’ popular OAuth 2.0 with Layer 7 Gateways series, with expanded notes and commentary. It also includes one or two of my own tutorials. Over time we’ll be adding demonstrations of how Layer 7 enables connectivity to commonly used OAuth implementations at various social and business networks, including Twitter and LinkedIn.

The tutorial demonstrates this thorough the addition of a new parameter, which is extracted from transaction metadata and then used to tweak the implementation. Specifically, I create a policy in which the authorization token’s lifespan is shortened if the user comes in from the browser of a mobile device.

The scenarios I’ve presented in these tutorials represent the two biggest strengths of the OAuth Toolkit – adherence to the specification when you need it and flexibility when you need that.  Our customers have taught us that every OAuth implementation is slightly different and our aim is to give them the tools they need to adapt.

My colleague Francois Lascelles recently launched a series of tutorial videos demonstrating how Layer 7’s OAuth Toolkit allows enterprises to use OAuth 2.0 to create some really interesting, powerful interaction scenarios.  However, the OAuth 2.0 specification isn’t 100% stable yet, so a real-world implementation must also be able to deal with 1.0a and OAuth WRAP.

For this reason, I’ve come up with a couple of additional tutorials that will demonstrate how our solution can be customized to meet changing requirements. My first tutorial, below, demonstrates a sample application using OAuth 1.0a, which exposes an interface that allows consuming applications to request access tokens and enables users to authorize those apps.

Watch this space for my second video, which will demonstrate how the OAuth Toolkit can be used to customize your implementation.

For situations where a service subscriber already has an SSO experience provided by CA SiteMinder, the SecureSpan Gateway can be leveraged to enable an application to consume the API on behalf of the subscriber, using OAuth. The objective is to maintain the end user’s SSO experience during the handshake while still complying with the OAuth 2.0 specification.

Tutorial 5: Leverage a CA SiteMinder Session in an OAuth 2.0 Handshake

To give you a general idea of what we’re dealing with in this tutorial, here’s a quick overview of how the authorization code grant type works:

• The resource owner is redirected by the client application to the OAuth authorization server, to express authorization (authorization endpoint)
• The OAuth authorization server redirects the resource owner back to the client application, along with an authorization code
• The client application  presents this code to the OAuth authorization server (token endpoint), along with its credentials, and gets an OAuth access token
• The client uses the access token to call the service on behalf of the resource owner (optionally the client can use a refresh token to extend the session)

For more information on the workings of the authorization grant type, watch my tutorial video below. Next week, we’ll be looking at the implicit grant type. In the mean time, for broader insight into how Layer 7’s SecureSpan and CloudSpan Gateways enable OAuth, read up on the Layer 7 OAuth Toolkit.

Tutorial 2: The Authorization Code Grant Type

I recently launched a series of video tutorials in which I provide practical instructions on using OAuth with Layer 7’s SecureSpan and CloudSpan Gateways. Layer 7’s OAuth 2.0 template implementation provides a standard-compliant OAuth solution to which you integrate your API, identity providers, API keys and so forth.

The Layer 7 OAuth Toolkit also includes client applications for testing each grant type defined by the specification. This is very similar to what Google provides with the Google OAuth Playground. You can test the OAuth handshake and test calling an API using the access token provided by the handshake. You can also test token revocation and token refresh.

Embedded below, the first tutorial in the series – Incorporate an Existing API & Identity Provider – shows how our template allows you to leverage existing resources in an OAuth deployment.  Over the coming weeks I’ll be posting all the tutorials in the series. In the meantime, for more information on how our Gateways enable OAuth, download the OAuth Toolkit data sheet.

OAuth 2.0 with Layer 7 Gateways, Tutorial 1: Incorporate an Existing API & Identity Provider