Question

I see APIs such as PayPal, etc. offering to call their services using NVP or SOAP/WSDL. When using a .NET environment (3.5) using traditional web services (no WCF) which is better and why? I know WSDL lets you drop in the API URL and it generates the wrappers for you. So then why do companies even offer NVP?

Answer 1

There seems to be never-ending confusion in this industry about the different types of web services.

SOAP is a messaging protocol. It has as much in common with REST as an apple has with a lawn tractor. Some of the things you want in a messaging protocol are:

• Headers and other non-content “attributes.”
• Addressing – routing of a message to different servers/recipients based on the headers;
• Guaranteed delivery via queuing and other methods;
• Encryption, signing, and other security features;
• Transactions and orchestrations;
• Accurate representation of complex structured data in a single message;

…and so on. This is not an exhaustive list. What WSDL adds to SOAP, primarily, is:

• Discoverability via a contract, a form of machine-readable “documentation” that tells consumers exactly what is required in order to send a message and allows proxies to be auto-generated;

• Strict, automated schema validation of messages, the same way XSD works for XML.

REST is not a messaging protocol. REST is a system of resources and actions. It is a solid choice for many architectures for several important reasons as outlined by other answers. It also has little to no relevance to “NVP” services like PayPal and flickr.

PayPal’s NVP API is not REST. It is an alternative, RPC-like messaging protocol over HTTP POST for clients that don’t support or have difficulty supporting SOAP. This isn’t my opinion, it’s a statement of fact. One of the fields in the NVP is actually METHOD. This is clearly RPC verbiage. Take a look at their API for UpdateRecurringPaymentsProfile and try to tell me that this makes a lick of sense to describe as a “resource”. It’s not a resource, it’s an operation.

In the case of PayPal specifically, the “NVP” (HTTP POST) API is inferior to the SOAP API in almost every way. It is there for consumers who can’t use SOAP. If you can use it, you definitely should.

And I’m not necessarily bashing PayPal for this, either. I know a lot of folks have bashed them for not putting together a “proper” RESTful API but that is not what I am getting at. Not every service in the world can be accurately described with REST. PayPal isn’t really a resource-based system, it’s a transactional system, so I can forgive their architects and developers for not having a perfectly elegant REST architecture. It’s debatable perhaps, but it’s not black-and-white. It’s fine; I’ll just use the SOAP system if I need to.

Compare this to, say, the Twitter API. This is a true REST service. Every “operation” you can perform on this API is accurately described as either the retrieval or submission of a particular kind of resource. A resource is a tweet, a status, a user. In this case it literally makes no sense to use a complex SOAP API because you’re not really sending messages, you’re not performing transactions, you’re just asking for specific things, and these things can be described with a single URL. The only difference is that instead of getting an HTML web page back, you’re getting some XML or JSON data; the way you request it is exactly the same.

A REST Web Service usually (always?) uses HTTP GET for the retrieval of some resource. And Twitter does exactly this. GET still uses “Name-Value Pairs” – that’s the query string, ?q=twitterapi&show_user=true. Those bits after the ? are name-value pairs. And here’s a great example of why you would want to use REST over SOAP; you can hook this up to an RSS feed and get streaming updates. I can turn it into a Live Bookmark in Firefox. Or I can download it in JSON format and bind it to something like a jqGrid. The interesting thing is not that the request uses “Name-Value Pairs”; the interesting thing is that it’s a simple URL and can be consumed by anything that knows how to request a web page.

So to try and summarize all of what I’ve said, think of it this way:

• Use a REST API (if available) when you want to expose data, or consume or publish it, as a permanent resource.

• Use a SOAP API when the system is transactional in nature and/or when you need the advanced features that a complex messaging protocol can offer, such as RM and addressing.

• Use an RPC API (which includes just about any API that’s modeled entirely around HTTP POST) when there is no SOAP API or when you are unable to use the SOAP API.

Hope that clears up some of the confusion.