17

I've been reading a few REST tutorials and some of them says that in order to send data to a rest API you should send post data as an array, which is something like this:

$data = array('foo' => 'bar');
$rest->post($data);

Then there are others that say you should send JSON data like this:

$data = array('foo' => 'bar');
$data = json_encode($data);
$rest->post($data);

Not sure if there's a standard way of doing this or either if is fine but what is generally recommended when designing API's?

EDIT: There seems to be confusion. To clarify I agree JSON should be used for client consumption but this question is about SERVER consumption. Meaning should the SERVER accept JSON or POST data from its clients?

Improve this question
2
  • 1
    It depends on what this will be used for, if it will be used from something like JS JSON input might be better Commented Aug 11, 2012 at 20:46
  • This discussion might help stackoverflow.com/questions/8604717/json-vs-form-post Commented May 14, 2013 at 18:38

7 Answers 7

Reset to default
7

If you're the one creating the RESTful API, meaning your application is the server and is accepting requests, then your question seems confusing. Your application will not be sending any POST data; clients will be sending POST data to you.

With that being said, having an API which will accept JSON-encoded requests is possible, though would really only be useful for very niche scenarios. The vast majority of clients will be POSTing data to your API in the application/x-www-form-urlencoded format. PHP handles this behind the scenes for you, and exposes the data as the $_POST superglobal.

If you're talking about responding to POST requests, and what format you should use, then that will depend on what format the client wants you to send it in. The client will either specify this in the Accept header, or some APIs allow it to be specified in the URL (e.g. foo.com/some/thing/123.json or foo.com/some/thing/123/json). The client isn't required to tell your application what format it wants, so it's up to you to pick a sensible default. Most APIs will use JSON these days.

I've never heard of an API that understood serialized PHP array format, though, so I don't know what resources you've been reading, but I'm pretty sure you misunderstood what they were suggesting.

Improve this answer
Sign up to request clarification or add additional context in comments.

15 Comments

I am the one creating API and this question makes perfect sense because if the client sends me (the server) a JSON string I cannot read it with $_POST, I need to use other means (e.g., parse_str(file_get_contents('php://input'), $data);). So this question is important because both ways are possible (JSON or POST array). The consensus is JSON is universal but as you said, some will use POST array so that is the reason of my question. Which is which?
@IMB: Yes, that code is written in PHP. But clients won't be POSTing to your API using PHP. They're be POSTing to it using JavaScript, in all probability.
Yes that is written in PHP obviously, but the data is transmitted as JSON. Wait, why are we arguing about this? Regardless whether it's PHP, ASP, JS, etc, it is json encoded. The question is between clients sending as POST array vs POST JSON. Both can be accomplished no matter what language.
@drrcknlsn I actually came to this page because I had an exact same question. Answering questions is one thing, but starting it with a qualified 'this is dumb' is not the way to start it, especially since the context makes it fairly clear.
@Pier1Sys: His context didn't (and still doesn't) match his actual question, and I made note of that mismatch by saying that it wouldn't make sense to be posting to an API in the manner he used in his example. When something doesn't make sense, I don't consider it insulting to say so. I certainly didn't tell him that his question was "dumb" - that's your own misinterpretation.
|
2

Actually, I think this is a pretty good question. don't know why it got downvoted.

Also, contrary to what I saw written in some comments, the client can use any language he wants, not only javascript. And it's not the server job to know which language was used to "build" the request, just that the request is valid. This makes more sense if you think that the entity making the request can actually be another server (think about a proxy server used to send post requests across domains).

That being said, personally, I think it's better for the server side to consume a XML or JSON. The main reason is validation.

It's easier to validate a XML or JSON against a schema. Also the schema can be made public, and a well designed schema can describe webservice by itself. The client can even use the same schema to validate the request prior to sending it to the server.

Passing an url encoded form is also valid, of course. And can be validated server side as well. SO i think, down the road, it's just a matter of preference.

Also, check this discussion in SO, it regards the same topic:

JSON vs Form POST

Improve this answer

Comments

1

You should think about the clients that will consume the API. A HTML5\AJAX client will probably want JSON data, while other clients (Silverlight or native mobile apps) might be better at consuming XML.

One great framework\platform for writing REST API's is looking to be Microsoft's Web API (based on ASP.NET MVC). The product succeeds the WCF framework and allows users to write REST API's in a MVC environment. One feature is that it chooses a serialization provider based on the HTTP Accept header.

So if a client Accepts application/json they work with the service in JSON and if the accept XML they work with the service in XML. You can also write your own object serializer and plug it into the framework.

More information: http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/video-your-first-web-api

Improve this answer

2 Comments

Note that is not about what the client consumes but what they send.
Still feels like if I'm best as consuming JSON, I'm going to want to request with a JSON formatted request and if I'm best at consuming XML... then I'm best at formatting XML requests. Web API handles serialization in both directions.
1

Most of the time you would want to stick to receiving POST data but I think receiving json data does have its uses for example when it comes to batch requests.

The Facebook API uses it.

You don't need to do file_get_contents('php//input'). From the facebook documentation you could just do something like this:

curl -X POST "http://example.com/batch" -d 'batch={ "param" : 1, "param2" : "2"}'

Then in the PHP code, if you're using PHP, you can get it through the $_POST parameter and do a json_decode. 

var_dump($_POST);

array(1) {
  ["batch"]=>
  string(30) "{ "param" : 1, "param2" : "2"}"
}

var_dump(json_decode($_POST['batch'], true));

array(2) {
  ["param"]=>
  int(1)
  ["param2"]=>
  string(1) "2"
}
Improve this answer

Comments

0

JSON makes more sense, since it is language-independent and can be useful when API scales.

Improve this answer

8 Comments

Correct me if I am wrong but aren't all language able to send POST data as array?
He's saying that every platform will be able to read JSON, without fail. The PHP array format may be misinterpreted on certain platforms.
Why would I want to send an json encoded string to an api? I mean look at quite every restful api out there, you call the defined url with your parameters urlencoded in the body if it's a post, put or delete or in the url as parameters? Or did I miss something here?
@GundarsMēness but they consume the response. IMB was asking about the request. Not the response. Sure that the response being a json string fits most apis perfectly.
@GundarsMēness as reiterated by mAu this question is not about consuming data but sending.
|
0

I am currently developing a REST API and I was asking myself the same question. After some research I found out that is no standard and is totally up to you.

You are developing the server side so you can decide how data should be sent to you. The client need to adapt to your design.

Personally I choose to receive all POST and PUT data as JSON directly in body.

Improve this answer

Comments

0

The point is to reuse the HTTP implementation that already exists.

HTTP is built to accept many different content-types and you only need to specify which you are using in the headers.

A REST API that accepts the various formats and works off the content-type header is refreshing. You can submit x-www-form-urlencoded values from an HTML webpage or make an AJAX request with raw JSON and there is no confusion as long as everyone is following protocol.

As a developer you must choose the support your app will provide because you can't support everything. Typically it boils down to the support or convenience of your own environment -- nobody wants to reinvent the wheel.

Many frameworks that are designed with building APIs in mind, handle the most popular content types at a lower level. They may also encode the response data according to the "Accept" header.

Implement whatever you think will be used most first or find a framework that already speaks HTTP and takes care of all of that for you.

Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.