JSON data to web service- how do define expected J

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 in? I am new to JSON and don't think I have a grasp 100%.

Will the other users system basically create a data structure (such an array) with the key value pairs that I need, encode this in JSON and send it to my web service?

Do I literally give them a copy of what the array needs to look like? Thanks!

Answer 1

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.

Answer 2

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.)