Should a web service enable the user to Create and Update, or just Save?

Question

When designing a web service that will allow the consumer of the service to save and get a complex data type (say Foo), should the service expose Create(Foo) and Update(Foo) service calls, or should the service expose merely a Save(Foo) service call? If Save(Foo) is better, should the user be able to predict whether the system will create or update (based on the content of Foo), or should the system simply create or update based on whether the Foo exists or not?

Assume that we want a simple interface and do not want to confuse the consumer with multiple ways to do things, but we also want to ensure unexpected results do not occur.

I can see pros and cons to each, but before I bias your answer, what do you think?

Finally, are there any articles out there on this subject?

(search engine help: Create vs. Save, Update vs. Save, Create/Update vs. Save)

Answer 1

It is totally dependent on how you want to design it. One of the best/most successful web-service APIs that I have used is the one published by Salesforce.com. They have 3 service calls:

1. create() - Always creates new objects
2. update() - Always updates existing objects. An ID field must be present that is used to match against. If the ID is not found, the update fails.
3. upsert() - Either creates or updates a record. This service call requires an "ExternalId" field that is matched against. For example, if you run an upsert() call against the "Email" field with email equal to "[email protected]", Salesforce will try to locate the appropriate record. If found, it will update the record, otherwise it will create a new record.

One thing that allows them to do this is that every object has a Salesforce generated ID field.

If you are interested, here is a list of all of their core web-service calls:

http://www.salesforce.com/us/developer/docs/api/index_Left.htm#StartTopic=Content/sforce_api_calls_list.htm

There aren't too many, but it more than gets the job done in most cases.