Google Cloud Endpoints - Making calls with JS client, passing params and JSON body

Question

I am having some trouble understanding some documentation on this. Located at ...

https://developers.google.com/appengine/docs/java/endpoints/consume_js

specifically ...

// Insert a score
gapi.client.tictactoe.scores.insert({'outcome':
    'WON'}).execute(function(resp) {
  console.log(resp);
});

// Get the list of previous scores
gapi.client.tictactoe.scores.list().execute(function(resp) {
  console.log(resp);
});

Seems like they are passing a score object, as JSON in the request body, to their API call for adding a score. Okay, sounds cool. It's unclear though on how you would pass a query parameter, URL parameter, or may be all three at the same time.

Would they be three JSON objects like this ...

gapi.client.tictactoe.scores.insert({
    'outcome': 'WON'
},
{
    urlParamName: 'value'
},
{
    queryParamName: 'value'
},).execute( ...

Or are they all in the same JSON object? That may very well be the case since Endpoints dosn't allow any name conflicts between params and members.

I can't seem to find documentation on this, could someone simply help me out so I can know for sure what's the format to pass these things? Thanks.

Answer 1

Unfortunately this isn't very well documented, except for some small mentions, e.g. here

Usually API methods are called liked this:

gapi.client.myapi.myresource.mymethod(params)

params is a JSON object that includes all query and path parameters, as well as a resource which would be send as body in a POST request.

Actually in the example above they are sending outcome as a query parameter as a POST request to tictactoe\v1\scores?outcome=WON with an empty body. This works since Cloud Endpoints don't make a difference merging the request object from the body and query and URL parameters. This works in this case but will fail as soon as you have nested JSON Objects inside of the request body.

The correct way to call above method would be

gapi.client.tictactoe.scores.insert({
    'resource': {'outcome': 'WON'}
})

If you have query and URL parameters this would look like this:

gapi.client.myapi.myresource.mymethod({
    'param1': 'value1',
    'param2': 'value2',
    'resource': body
})

where body could be any JSON object. Or for methods that don't need a body you would just have

gapi.client.myapi.myresource.mymethod({
    'param1': 'value1',
    'param2': 'value2'
})