RESTful web services - best way to return result of an operation?

tags:

rest

views:

answers:

+2 Q:

RESTful web services - best way to return result of an operation?

I am designing a RESTful API and I would like to know what the most RESTful way is to return details about an operation.

E.g. an operation on a resource occurs when some data is POSTed to a URL. HTTP status codes will indicate either success or failure for the operation. But apart from success/failure I need to indicate some other info to the client, such as an ID number.

So my question is, should the ID number be returned in an XML document in the response content, or should it be returned in some custom HTTP header fields? Which is more in line with the principles of REST? Or am I free to choose.

XML document makes the most sense.

Tom Cabanski 2010-04-20 01:47:40

because.........?

Michael Haren 2010-04-20 01:50:49

It's what I've seen most often. Headers are less obvious.

Tom Cabanski 2010-04-20 01:52:41

But is this RESTful? POST does not request a resource in REST, it modifies one. Most examples I've seen return the location of the new/modified resource in the Http header's Location field. Client is then free to request it if they want to see what they just modified.

saille 2010-04-20 02:24:46

If it is a just an ID number, it would save overhead to do it just as an HTTP header. Building a correct XML document just for a single number would add much more overhead to the request.

webdestroya 2010-04-20 01:48:42

But what's the right thing to do? What will clients understand most easily?

Michael Haren 2010-04-20 01:50:15

I guess that depends on the client... personally I would prefer JSON over XML

webdestroya 2010-04-20 01:55:38

I meant why a document response instead of headers...I think that's what the original poster is asking, too

Michael Haren 2010-04-20 02:00:00

Yes, I'm talking a document vs header field for the ID returned. Document encoding type is irrelevant to the question.

saille 2010-04-20 02:27:03

Well a header uses less space, but a document would be more readable by a person.

webdestroya 2010-04-20 02:36:23

How did you determine that a header uses less space? If my header is x-Created-Id: 45 and my response body is <Id>45</Id> then the header is going to take more bytes.

Darrel Miller 2010-04-20 02:42:37

Because that isn't well-formed xml, you are forgetting the `<?xml version="1.0" encoding="utf-8"?>` that should be on top, which would definitely push it over the limit.

webdestroya 2010-04-20 03:01:59

An xml document does not require the Xml declaration to be considered well formed. See http://www.w3.org/TR/REC-xml/#sec-prolog-dtd Also, there is no need to use XML at all. Using text/plain as the content type would allow the body to just simply be 45.

Darrel Miller 2010-04-20 03:08:21

Yea, echoing just "45" in the document body would probably be the cleanest solution, I just figured the OP was looking for JSON/XML system. +1

webdestroya 2010-04-20 03:31:45

+2 A:

Returning an entity is a perfectly valid response to an HTTP POST.

You also do not need to return XML you could just use the content type text/plain and simply return a string value.

Using a header would require you to define a new custom header which is not ideal. I would expect clients would have an easier time parsing a response body than extracting the information from a header.

Darrel Miller 2010-04-20 02:38:04

ansaurus

tags:

views:

answers:

RESTful web services - best way to return result of an operation?

related questions