A public web API: What do developers prefer to consume?

Question

We've got a bunch of data that we'd like to expose to the world hosted on an asp-net.mvc website. I'd like to ensure that we deliver it using technology that is easy for end developers to implement and not tied to any particular platform, rather than using technology that is unpopular/incompatible with developers.

The kind of requests we expect are mainly to retrieve search results (not many parameters), but down the like we'd like to be able to provide catalogue lookups and the like, which may be more complex.

Bearing this in mind, what is the preferred means of doing this?

Answer 1

Windows Communication Foundation can be used to create both SOAP services (great if your consumers are businesses, using Visual Studio/.NET or Java) or REST services (for people on other platforms). Those are the preferred means of exposing public APIs.

If you want maximum exposure, probably best to use the REST approach, since it is easier to consume from "web" languages like JavaScript. Microsoft has extensive resources on putting together a REST API using WCF.

Honestly, for the kinds of requests you say you need to handle, which all seem to be looking up data as opposed to modifying it, the difference is almost trivial - you can switch from SOAP to REST simply by changing a few attributes/configuration options and you could technically even host both at the same time using very little additional code. As long as you stick to WCF and don't use outdated technology like ASMX/WSE then you will be fine.

Reasons to use REST:

• Consumable from almost anywhere (including JavaScript, RSS readers, etc.);
• It's popular (in use by Google, Twitter, etc.)
• Supports many different data formats (JSON, Atom, etc.)

Reasons to use SOAP:

• Standardized security protocol (encryption, non-repudiation, etc.)
• Distributed transactions
• Message Queuing

That's not an exhaustive list but it should give you an idea of who the target markets are for each. If you're hosting a very open, very public site designed to be consumed by anyone and everyone, go with REST. If the service is part of a business system and you need to guarantee reliability, security, and consistency of data, you'll want to go with SOAP. Choose the appropriate technology based on your target market.

Answer 2

Create a RESTful API. As a developer who often consumes web services, it's what I would expect and prefer.

Many popular services (digg/twitter/netflix/google) are moving to REST over SOAP, so you would be wise to follow suit.

Answer 3

If you do create a REST API you should also create a WADL file. It's WISDL for REST. They're not well supported yet, but they're not hard to create and they'll become more useful as support increases.

Answer 4

YOu will want to check out odata. Look at odata.org and live.visitmix.com/videos This will give you REST access, metadata support like in SOAP, interoperability with the whole office stack and if you are using WCF Data Services you can implement it in a matter of hours, days at most.

Take a look at netflix.com, they have done it right (IMHO).