Advantages of Name Value Pairs to SOAP/WSDL

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

I assume that by Name Value Pairs, you mean REST services.

The benefits to REST are primarily ease of development, simplicity and elegance, and lower overhead (which is very important if you are sending and receiving a lot of small messages).

Here are some of the advantages of REST:

• REST is more lightweight
• Human readable results
• Everything is a URI addressable resource
• REST services are more easily cached
• REST is easier to build (no toolkits are required)
• REST is easier to call (HTTP - GET, POST, PUT, DELETE)

Answer 2

NVP is HTTP POST

name=fred
amount=100
code=403

etc

This is the default format from any HTML browser so it's simple to implement for sending data to a web service

I don't think it's a good format for receiving data from web service? JSON or XML would be more suitable

No everyone uses VisualStudio, or has access to automatic wrapper generators, or wants to use such a beast

Many web mashups are coded in Javascript, so using HTTP POST to send data is the simplest way. The return result is a standard HTML response code (200, 403, 500, etc) and/or some JSON

Many service providers offer multiple API's to cater for all customers

Answer 3

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.