Choosing between performance and ease of use in WS API

Question

We're in the process of creating a new API for our product, which will be exposed via web services. We have an internal debate whether the API should be as easy as possible to use (in the price of making more calls) or make it as efficient as possible (rendering it harder to use). For example, here are two issues that came up:

• Should we manage session info on the server, or should we pass that info back to the user, and expect him to send it back to us when needed? (Please ignore the security implications of a session)
• Should we combine calls that are likely to be consequent, in order to save the time spent on the round trip in between, even if they don't really share the same logical functionality?

Basically, the desktop people are in favor of a clear, easy to use API, while the internet people would like to make it as efficient as possible. This is the first public API we're providing, and we need a strategy.

Personally, I'm in favor of making the API as usable as possible. Other components on the system are probably going to have a much larger affect on the performance, and hard to use APIs are much more error prone. But I'm a desktop programmer…

So, what should be our strategy? What are the common practices when creating such an API?

Answer 1

IMO, the best is to have the simplest API for people who will have to use your API, but letting these people have deep customizing possibilities, to make it efficient, even if harder to use.

But simplicity for users > all.

Answer 2

What are typical usage scenarios? Will the latency of your API determine the UI responsiveness? How big the performance trade-off will be? It's hard to suggest anything without knowing your circumstances.

But

1. My guess is that passing session info to the client will scale better. In-proc session management won't allow you to share the state between service instances. Managing sessions in DB will make your services more complex. Anyway this all depends on your bandwidth/memory/computational power capabilities.

2. I would start from the most granular operations and only provide composite methods when performance problem becomes obvious.

Answer 3

I would recommend you create your web service following the RESTful model and that means stateless. Efficiency is more critical than ease of use. You can always create a framework on top of the API later that eases implementation headaches.

Answer 4

You're debating a circular agrument. This is all usability (ease of use).

You're likely going to factor in a bit of both aspects - as they both influence user performance.

Its a case of (i) extent of customsiable features versus (ii) efficiency in manipulating those features. There will be an intersect between the two.

I'd say give a simple API that puts control into the users hands - this is the primary purpose of CMS. The more detailed aspects you could combine initially, introducing them as added control later on.

This way you will manage users learning curve of the system so as (i) not to bombard them with excessive options initially and (ii) allow them to adopt your system quickly at first. Then extend your users control (system functionality from a user perspective) later on by making more of the API features available.

Another good tip would be to ask you users upfront & as you go.

Answer 5

My 2 cents:

First start with a very granular low level API that gives high performance. Then create a easy-to-use high level API that is "composed" of the above low level API.

This way clients can customize their behavior as they want. The clients can start with using the high-level API but if high performance is expected for certain user actions, they can use the faster-but-difficult low level API on a case-by-case basis.

One more important point to consider in service design. Try to keep them as stateless as possible. The advantage of stateless web services is that they can be easily distributed using Network Load Balancing.