0

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!

Lock
  • 5,422
  • 14
  • 66
  • 113
  • 1
    It's common for a REST service to **output** JSON-encoded data; you really are taking **input** as JSON-encoded (and not standard GET query parameters or POST data values?)? – MidnightLightning Sep 26 '12 at 12:06
  • What is the most common? If POST values are the standard, then I will go with that. The service will accept many product codes/quantities. How do you pass this data through a POST? something like: product_1=item1&product_1_qty=2&product_2=item2&product_2_qty=5? – Lock Sep 26 '12 at 12:10
  • For updating data, yes, POST is common and required for the RESTful methodology; see my answer for full explaination – MidnightLightning Sep 26 '12 at 12:15
  • possible duplicate of [JSON schema validation with PHP](http://stackoverflow.com/questions/2757662/json-schema-validation-with-php) - you validate against the Json schema, see http://json-schema.org/ – hakre Sep 26 '12 at 12:28
  • POST data doesn't actually have to be a query string. It is perfectly valid to post JSON-encoded data - the format of the POST data is defined using the "Content-Type" header of the outgoing request, which defaults to "application/x-www-form-urlencoded", but can be anything. If you're storing JSON data, then accepting JSON data through POST seems reasonable to me. – cloudfeet Sep 26 '12 at 12:40

2 Answers2

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

MidnightLightning
  • 6,715
  • 5
  • 44
  • 68
  • Thankyou- very good answer. So, say for a shopping cart for example, how would the products be passed in the query string (as there may be many products?). Do you just do something like "product_1=test&product_1_qty=4&product_2=test2&product_2_qty=9? etc? – Lock Sep 26 '12 at 22:35
  • For adding products to a cart, you could organize it that way. Or, have the end user call the "add to cart" method multiple times, once for each product: Endpoint `/api/cart/1243/add` with data `product_id` and `quantity` called however many times is needed. – MidnightLightning Sep 27 '12 at 11:46
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.

faizan
  • 680
  • 1
  • 6
  • 15