Video and Slides: Is your API naked?  API Platform and Ops Considerations »

Thanks to all that attended last week's API Best Practices Webinar #5 "Is your API Naked? API Platform and Operations Considerations" (and thanks to our presenters @gbrail and @landlessness). Video and slides are below.

Our next API webinar, "Your API Sucks!  Why developers hang up and how to stop that" with @landlessness and @earth2marsh, is June 14th at 11am PST (sign up here!)

(And you can see all our API best practices webinars to date here)

Video and Slides: API Metrics - What to Measure »

Thanks to all that attended last week's API Best Practices Webinar #4, API Metrics - What to Measure (and thanks to our presenters @brianpagano and @landlessness). Video and slides are below.

Our next API webinar, "Is your API Naked? API Technology and Ops Considerations" with @landlessness and @gbrail, is June 14th at 11am PST (sign up here!)

Design your API for adoption with ‘true REST’ »

"The only reason you'd have only a SOAP API is because you hate 80% of your addressable market." - @sramji

There's usually little argument that a REST API is easier to use than a SOAP API.

But how important is it to be 'truly' or 'strictly' RESTful? That is, adhering to standard HTTP operations or 'verbs' - GET, PUT, DELETE, POST - on well defined resources, as opposed to the common practice of embedding 'verbs' or operations as methods in a GET URL.

Typically, security is cited as the big advantage of 'true REST' (with some good discussions here and here).

However, a truly RESTful API may help you boost developer adoption. For example, imagine a 'shopping cart' API:

While the above API isn't 'truly RESTful', it's not that hard to use.  But you do have to learn the individual operations and this can get cumbersome if there are a lot of them or as the API evolves.

Instead, this 'true REST API' may be easier to learn and predict as you use more features.

What if we want to list all the shopping carts in the system at any one time? We would add that via an HTTP GET to:

http://api.shopping.com/carts.xml

Query parameters can still serve a purpose - making it possible to specify additional options. For instance, imagine a very large shopping cart, and you want to "paginate" the results. To look at items 20-29, you might use a URL like:

http://api.shopping.com/carts/X.xml?start=20&;count=10

Bonus: True REST makes analytics easier

It's a lot easier to build reports that segregate and analyze traffic by URL than to build logic that tries to do this by methods or combination of methods. Good API analytics helps you optimize features, debug problems, and weed out traffic that can slow down your service.

What if your 'non-strict' REST API is already out there?

It might not be that big a deal if your API is very simple or 'read-only' API with information that isn't too sensitive (such as a free search API). Or you can map a non-RESTful API into a 'truly RESTful" API with custom code or API management tools thatperform API transformations.

* A note on POST VS. PUT

* One way to insert an item in the shopping cart is to use POST to update the shopping cart by sending it a new item. In this case, we are using POST to send the server an instruction that essentially tells it to insert some new content to the existing resource. This is why we use POST -- it is like an "update" in a database.

Alternately, we could add the item by using PUT to a new URL, such as:

PUT http://api.shopping.com/carts/X/items/Y.xml

But if we do this, then we need to somehow give our item some sort of unique URL by picking a value for "Y". This is kind of a strange thing to do, so it may be more natural to use POST and have the response include the URL for the new item, so that we may retrieve it later using GET or delete it using DELETE. Still, sometimes using PUT like this makes sense.

This all comes down to the difference between PUT and POST in the HTTP spec. POST modifies something that already exists, and how that thing is modified is up to the server. PUT replaces the entire contents of the URL with new data. Plus, like GET, HEAD, and DELETE, PUT is idempotent, which means that if you call it more than once, it has the same result every time, whereas POST may keep doing what you ask it to do over and over again

But can you hold the API to the SLA? »

Great article by Jonathon Feldman in Information Week recently with some steps for CIOs to take before getting into cloud computing.   One is to insist on SLAs from cloud providers, especially considering the natural tension from the provider's perspective between high-availability and low-cost operations.

Absolutely agree.  But to build on this - remember that scene from Seinfeld where Jerry is at the car rental counter -  "Anybody can *take* a reservation, the important part is to *hold* the reservation."

Often, cloud and API providers will agree to SLAs, but have limited means to enforce or verify the SLA is held. Many SLAs are just 'on paper' with minimal enforcement or monitoring.  This gets especially tricky if you need to discuss financial penalties. 

Consider how you will monitor, meter, and audit API traffic and content between you and your partners - from your side - in order to pinpoint problems, protect your organization, and especially if you need to enforce penalties based on SLA misses. 

Why modern applications need an API proxy »

Structures of control are spontaneously generated in every environment and every wave of computing.

Today on the web we have a model where browsers are the single point of control for much of what happens, not just at the level of applications, but at the meta-application level as well. Not simply usage (“point-click-type”), but things about usage – who is the user (browser cookie), what are they using the app through (user agent), where did they come from (referrer), what can we infer about their behavioral state, and so on – as well as modifications of usage (browser add-ins, content filters, security modes, local caching for performance). To be sure, some of these things can be and are performed using infrastructure between the browser and the website (such as content filtering, security, and caching), but the guaranteed component is the browser.

This is one of the reasons that Google Analytics is so popular and useful – you can rely on it to tell you useful things about your traffic because it can rely on the browser as a predictable point of control. Including an invisible piece of content on your web page makes the browser fetch data from Google, implicitly sending information that enables Google to report on your usage.

For web and cloud APIs, what is the equivalent structure of control?

Currently there is no one point like the browser. This is for great reasons – APIs are all about reusing application or service logic and rendering it to different form factors: pure logic (built into an internal application computation), web UIs (part of a mashup), and most notably, client applications on a wide range of devices (from PCs to mobile phones, set-top boxes, and tablets like the iPad). These devices are in the early part of a boom that will see over 10 billion individual units in use, representing at least hundreds of unique hardware/software designs. The sheer utility of these internet-connected devices predicts that their usage will drive high demand for APIs rather than standard websites. There are initial specifications like BONDI that suggest a standard contract across all of these for “mobile web applications” that include interaction with the features of the local device (such as a camera or GPS) but they are years from broad adoption and don’t attempt to unify all API access down to a common control point.

Given that APIs are to application logic what RSS is for content, we know they will be very important; at least as important as the visible web that we use today and possibly more important. This suggests that the other things that are spontaneously generated in value-exchange environments like user/customer management, behavior analysis, content filtering, caching, and security – will show up for APIs as well.

The web API equivalent of the browser’s control structure is an API proxy.

This is a control point which unlike a web proxy is fully aware of API content, communications patterns, and able to drive the meta-application controls discussed above. An architecture like Google Analytics which is founded on a browser’s predictable algorithms cannot work in an API setting. The same rule applies to add-ons that modify usage – they can’t do so relying on the local device if they are to be widely adopted. But an API proxy – a server or service on the internet, sitting between the client (regardless of type) – is able to be that point of control. As traffic runs through it, meaningful data can be captured for immediate outcomes (block access, change the message, or respond from a cache) and later used for behavior analysis and business planning. Add-ons that modify usage of the API can be installed at this point (content filtering, adding new information such as advertising, or identity management). All of this can be done while adhering to the contracts of the APIs and supporting the web architecture and rules of HTTP-based applications, and without attempting to solve the logarithmically complex problem of modifications to all the world’s clients.

So API proxies are likely to be necessary for the sustained growth of web and cloud API usage. There are likely to be several nuances that end up differentiating the different implementations and providers of API proxies. The key is to start experimenting with them now in order to build better apps and stay ahead of the competition.

Tech Talk: API Visibility and Metrics »

Earlier this week, Greg speculated that Twitter might have benefited from digging deeper into API metrics and usage patterns, so we thought it would be a good time to put him on the spot with a tech talk he recorded on API visibility a couple weeks ago. 

For more, here are some sample API metrics considerations and a demo of our own API Analytics solution.

TrueCredit.com API case study »

Scott Metzger, CTO of TrueCredit.com was kind enough to take some time to talk about their Consumer Connect API program and some of the technical challenges that they have addressed using Apigee's API Gateway.

Scott wanted to make life easier on his development team as they ramped up their number of APIs, partners and traffic volumes.  Here, he describes how he uses the technology as a 'policy layer' to provide API analytics, fine-grained data protection, and caching in an API Gateway. In this case, Apigee Enterprise is deployed on-premise virtualized software.

We're very excited to be working with Scott and TrueCredit, and check out the full TrueCredit Case study. 

Is your API naked?  10 API roadmap considerations (part 1: visibility) »

We'd like to run a short series on product and technical requirements you might consider for an API roadmap or strategy.    We’ll base this on trends we see in talking to hundreds of product and engineering managers that are either opening or consuming APIs (or aggregating and publishing large numbers of RSS feeds.)

Instead of talking about your APIs functionality, this is about what's *around* the API features and data.  Many APIs start out as just raw naked back end features. And there is often a big gap between a raw feature and a full-fledged service, which is your API might eventually become.

So this series is about what's needed to "monetize", "productize", or "operationalize" an API.  And not just if you are providing an API to customers – much of this applies if you are consuming APIs as well.

Topic #1: API Visibility

We're always surprised how almost every company we talk to says how little they know about their API traffic and usage.   We see lots sifting through web server logs to understand usage. As the API becomes more strategic and you want to make the case for more investment - this gets more painful.

This happens a lot when an API starts as an experiment, launched by the 'ask for forgiveness, not permission' types (you know who you are).  Things like metrics or analytics are back burner until an API either gets off the ground or doesn't.

But most APIs usually end up getting more important more quickly than expected, and as a product and engineering manager you may start asking:

Who is using the API and how much are they using?

• How many clients, apps, developers are out there?
• How do they break down by type, region, class of service?
• How does usage map to existing customer or partner organizations. Or how do developers map to applications map to customers?  (This can be tough with only key or IP based tracking.)
• What parts of the API and service are they using - on a method or operation level?   
• How does traffic breakdown between the your own products and 3rd party products?  (If they use the same API.)
• What the aggregate and per developer/app/customer transaction and data volumes?

How fast and 'good' is your service? 

• What latency are customers experiencing, by developer, customer, region, or operation?
• Where are errors and user experienced bugs happening and how often? 
• How is the API delivering vs. any formal SLA have agreed to or paid for?
• How can you find out if a customer is having a problem (before they call you)?
• How is the API usage impacting the rest of the platform or web products that also use the same API?
• Can you quickly trap and debug based on a specific message? Based on what is in a cache? streaming right now?

How does the API impact the business?

• Who are the top priority customers?  Developers?   Partners?  Who should you call to up sell to a higher service tier or do a deal with?
• What do you need to show general management to make product strategy (or tactical) decisions?
• Will you need to create audit trails or metering reports for partners that are paying for API access?
• Do you need to create metrics based on a certain data value in the payload? (Such as a specific product SKU)
• What is the cost of the data that you are serving up? (if you are licensing this data)
• Are you in line with all the compliance standards that IT enforces for the on-premise apps?

Knowing this stuff is really important when opening an internal service as an API, because now customers, contract terms, and compliance regulations come into play.  Analytics and metrics help you get proactive with customers and partners, and are critical when you need to make the business case for an APIs to executives.  You probably use web analytics to help you improve your Web UI - at some point you need this for APIs as well to see where to invest.

What's your experience?  We’d love to hear what you think.  Next up: traffic management.

SaaS API management and operations »

This week we'll be at the O'Reilly Velocity conference on scalability and operations in San Jose.   On the topic of API operations, below is a case study we did with Tim Madewell of Innotas, providers of on-demand IT Governance -  where he talks about how they operationalize and scale their SaaS API.

Tim talks about the importance of having separation and visibility between front-end and back-end service traffic.  We are seeing this use case more often as more web products are being built off the same API that is opened to customers and partners.  Because your web app is the biggest customer of the API, it's critical to be able to understand and throttle traffic into the back-end to make sure your web app performance isn't compromised by API usage by other clients. 

From a competitive standpoint, Tim makes a great point that it's critical to be able to assure enterprise customers that a SaaS API is as robust as anything their customer could build or buy on-premise - not only from a functional standpoint, but operationally in terms of security, compliance, control and scale.   

For more on this, Dana Gardner did a great podcast on Innotas API management at briefingsdirect.com