Question

I have a request where most of the input parameters are put in as a JSON request object. For documentation purposes, I want to specify the most common fields that a user can put in but there is a lot of variability to the name values that would go into the JSON request and I don’t want to document all of these as it would be cumbersome.

Here’s a screenshot of what I have now:

As an example if I wanted to put in a JSON property called “people-with” and set it to “[‘joe’,’paul’,’jane’] then that would be easy to do in the JSON but how would I pick that up in my PHP/Restler code. Right now the signature for this service is:

/**
 * ADD an Activity
 *
 * Add a new action to a user's stream
 *
 * @url POST /{user_id}
 *
 * @param integer   $user_id    The user_id for whom the actions apply; you can insert the text "self" and it will resolve to the current/default user
 * @param string    $start_time {@from body} The date/time that the activity was started (YYYY-MM-DD or YYYY-MM-DD HH:mm:SS)
 * @param string    $action     {@from body} The action "slug name" that uniquely identifies an action
 * @param string    $end_time   {@from body} The date/time that the activity concluded (YYYY-MM-DD or YYYY-MM-DD HH:mm:SS)
 * @param string    $app_id     {@from body} The application that captured this activity
 * @param string    $proxy_user_id  {@from body} The person who captured this activity for the individual
 * @param string    $location   {@from body} The location information associated with this activity
*/
public function add_action ($user_id, $start_time, $action, $end_time=null, $app_id=null, $proxy_user_id=null, $location=null)
{
    // implement
}

p.s. as a side note, I’ve temporarily changed this API service to a PUT to avoid the POST issue that was raised a few days ago which is effecting me here too while using POST.

Answer 1

Ok, key to solving this lies in the $request_data associative array. So in order to achieve both the documentation (of key fields) and being able to dynamically receive values into the POST/PUT service you just need to do this:

/**
 * ADD an Activity
 *
 * Add a new action to a user's stream
 *
 * @url PUT /{user_id}
 *
 * @param integer   $user_id    The user_id for whom the actions apply; you can insert the text "self" and it will resolve to the current/default user
 * @param string    $start_time {@from body} The date/time that the activity was started (YYYY-MM-DD or YYYY-MM-DD HH:mm:SS)
 * @param string    $action_nm  {@from body} The action "slug name" that uniquely identifies an action
 * @param string    $end_time   {@from body} The date/time that the activity concluded (YYYY-MM-DD or YYYY-MM-DD HH:mm:SS)
 * @param string    $app_id     {@from body} The application that captured this activity
 * @param string    $proxy_user_id  {@from body} The person who captured this activity for the individual
 * @param string    $location   {@from body} The location information associated with this activity
*/
public function add_activity ($user_id, $start_time, $action_nm, $end_time=null, $app_id=null, $proxy_user_id=null, $location=null, $request_data=null)

Note that there is no @param for $request_data but that $request_data is now hanging at the end of the function signature. Now imagine I had passed the following 'test' : 'me' in the request’s JSON. Now I can get that in my handler at:

echo $request_data['test']; // prints "me"

This works and the documentation looks as it’s supposed to as well (see screen shot above).

One final note, for those who are curious, you can access ALL your JSON variables through the $request_data array. So that means that:

echo ($request_data['user_id'] === $user_id); // TRUE