JSON data to web service- how do define expected JSON data

Question

I am building a RESTful web service in PHP that accepts JSON as its payload . Now, my question is, how exactly do I describe to the user the format that the JSON request comes i

Answer 1

Adhering to the guidelines of REST, the input you get from the users of the API should either be part of the URL (for a GET request; doesn't update data, i.e. http://example.com/api/doc/1243), or should be a POST variable (sent in the body of the HTTP request, to the same URL).

So for documentation, all you should need to do is indicate the endpoint URL (http://example.com/api/doc/1243), the fact they need to use POST, and what the variables are (i.e. title, body, author, etc.). Then users will form the proper HTTP request however they want, and on your server end, because you're using PHP, you'll pull their variables from the $_POST array (i.e. $_POST['title'], $_POST['body'], etc.)

Answer 2

Dropbox is a good example of restful api that uses JSON as payload.

You will also get a good idea about how you can document your API as well.