December 19th, 2012

API Design Tutorial: Pagination

Layer 7 Pagination Tutorial

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.

November 23rd, 2012

Our First API Academy Videos

API Academy Videos

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

May 23rd, 2012

Public APIs, Private APIs

Publish-a-Private-API-VideoWhen talking about API management, the first thing that comes to mind is a public API, one that is open for anybody to consume, provided a certain level of registration. Obviously, the most famous APIs are the public ones, potentially known to anybody. However, such APIs only represent a small subset of all APIs that need to be managed. Many APIs that we encounter in the field are set up in such a way that their consumption is restricted to a specific group of developers. This happens for various reasons. Some talk of public and private APIs, others use the terms open and closed to represent the same distinction.

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.

April 5th, 2012

Simplifying SOAP-to-REST Conversion

Written by

SOAP-to-Rest RemappingEarlier this week, Layer 7 CTO Scott Morrison presented our second Tech Talk Tuesday meet-up on Facebook, which concentrated on Simplifying REST Adaptation. For those of you who missed the live event, the recording is now available in the Layer 7 Resource Library. For those of you who attended, I thought I’d provide some detailed information on how Layer 7 facilitates bulk conversion of SOAP-based Web services to RESTful APIs.

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.

SOAP-to-REST Step 1

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

SOAP-to-REST Step 2a

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

SOAP-to-REST Step 2b

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.

SOAP-to-REST Step 3b1

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

SOAP-to-REST Step 3b2

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

SOAP-to-REST Step 3c

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

SOAP-to-REST Step 4

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

January 30th, 2012

Your One-Stop Shop for OAuth Tutorials

OAuth TutorialsThe ongoing explosion in the amount of online information generated by enterprises has created a need for open, distributed access – a way to get at online content that doesn’t require private user credentials to flow freely over the Internet. The OAuth specification has rapidly emerged as the key standard that enables this kind of delegated access.

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.