I’m an architect at the Rackspace Cloud and I work with Jorge Williams. I’m responsible for the part of the API system design that utilizes caching. The system will indicate to you that a cached entry was returned by using a 203/Cached response in cases where you repeatedly poll for something that has not yet changed state, or in cases where you are polling at a rate that’s impossibly fast. For example if you ask to reboot a server and ask 1000 times what it’s status is over the next minute before it’s even possible that the server has rebooted, and changed state. It’s a way we can gracefully indicate to the client to slow down the polling interval by consulting the max-age of the Cache-Control header along with the Last-Modified header value to indicate when you should poll again.

>As far as I (as a client) am concerned, there is no caching. Your
> implementation may cache behind the scenes, but it’s irrelevant to me.

That’s right, but we still respoectully indicate to you that we are doing that so that you have an indication of how to tune your polling interval for optimal results.

> But if that’s the case, then why does your API doc return a 203/Cached code
> and a “last modified” header? Why would I care if this supposedly cached
> content is guaranteed to be up to date?

Functionally you don’t care. but operationally you do. You’ll care when other users of the API service start sending in thousands of polling requests per second on operations that do database lookups or back-end system API calls to produce the answer. That use pattern would slow the system down considerably for neighboring users, including you. We use the caching as a coarse method of QoS admission control to determine how much back-end work we will do and at what rate.

I’m also responsible for the LIMITS design which further defines how often you should expect to run operations of various sorts. This is designed to control the rate at which we accept API calls that result in cache misses. By using these approaches in combination, we were able to produce an efficient system that gracefully handles most unintentional abuse of the API service. The neighboring users are efficiently spared from the unwanted work pattern, and very busy clients are minimally invaded by error conditions.

Rackspace believes deeply in transparency in everything we do. We produced a system design with a supporting API specification that allows us to be as transparent as possible about how we are handling things on the back-end of the API service. The limits are clearly available for the client to see, and by using our 203/Cached return code, you know when you’re asking for something too frequently.

Regards,

Adrian Otto

Very interesting and technical article and related list of posts …
Doing software since a long time, I think it could be great if all software vendors could take the time when submitting their API to: list their requirements, the non functional requirements and constraints, a high level UML model of the concept and then finally an API. When I was doing research it was also good to position itself towards existing stuff in the same area.
As a customer, my only feeling is that today exist around 5 differents specs that again will lock me in with a specific provider. It will also force me to “program” access to this API …
He Guys, do you think our Admins can program Java and are JSON and XML schema fluents?
At least we have some bloggers that take the time to make reviews.
Anyway, do you think my procurement manager will choose a cloud vendor based on its API? So if you want to be really user oriented, try to make it simple AND interoperable…

i don’t have experience with large scale clouds, we mainly use one of the clouds to help our customers with the infrastructure for bringing and keeping their applications available to their users.

there is the another benefit to a clear and concise interface to your cloud, big or small. you can manage your resources through different interfaces. and to keep your cloud ‘up’ you can use this feature.

we have created a native android application called decaf (http://decaf.9apps.net/), for managing amazon ec2 accounts. apart from operating your cloud artifacts you can now see the health of your own cloud graphically, for example. with a native android we are also able to monitor instances and receive/process sms alerts in a way that is meaningful.

with an application like decaf we could do other interesting things as well. you cloud offload resource intensive tasks to amazon ec2, from your phone. although i don’t see the immediate problem this solution solves it is interesting. but i think google apps is a more appropriate cloud for this model.

I’ll gladly take a look. But once again I am not giving thumbs up or down to any spec (though I may drop a few pointed comments here and there). I am mainly going through them in order to learn the industry state of the art.

WV

Thanks for another intriguing read – I know how much time it takes to write posts like this and I don’t know where you get it all from.

I’ve updated the temporary OCCI site to point at occi-wg.org and would like to hear your thoughts once we’ve got the current thinking own on paper.

Sam

Your second paragraph is great. It’s more or less what I was trying to say in my response to your previous comment, when I wrote “in the end it’s the actual application making use of the API which is RESTful or not. That’s where the moment of truth is.”

For all the talk about whether an API is restful or not, what really matters is how it is used rather than the details of what it spits out. It’s the usage model that you apply to it. The actual protocol may be more or less conducive to this model, but it is not the model by itself.