BETA

Newgrounds.io Help: Communicating with the Server

Posting to the Gateway

All calls to the API are done by posting to the Newgrounds.io Gateway at //newgrounds.io/gateway_v3.php. This 'gateway' processes any data you post to it, and responds with a JSON-encoded object.

Go ahead and load the gateway in your browser, and you will immediately see how it responds with a JSON object containing an error about missing required input.

The gateway script expects a single request parameter named 'input', and expects to receive it using the POST method.

If you were to load //newgrounds.io/gateway_v3.php?input=test (GET method) in your browser, you would see the same 'Missing required input' error as before. However, if we use the POST method, we get a different result:

We still get an error, but now it says 'Invalid JSON object in input'. This is because the input value is expected to be a JSON-encoded object, which we call the 'input object' (see below).

Let's do one more quick example, using a proper JSON-encoded input object:


The above example posts a valid input object, calling the Gateway.getTime component (see components list for more information on components).


The Input Object

As explained above, the gateway script will always expect an input object. This object is a container that tells the API what application is calling it, who the end-user is (if known), and what components we want to call.

An input object can have any, or all, of the following properties:

app_id (required)
This is the App ID found on your Newgrounds.com Project/API Tools dashboard (see Getting Started page for details).

call (required)
This can be either a 'call object' (see 'The Call Object' below) or an array of up-to-ten call objects if you want to call multiple components in a single post. If you are using encryption, some components will expect a 'secure call' object here (see 'Secure Calls' below).

session_id
This is a session ID string associated with your end user. (See Newgrounds Passport page for information on obtaining session IDs).

debug
Set this boolean to true to operate in debug mode (responses will contain more data, some features will only simulate posting).

echo
You can set this to ANY value, and it will be returned, verbatim, in the server response.


The Call Object

The call object is an object that defines which component to execute, and what parameters to call it with.

A call object can have any, or all, of the following properties:

component (required)
This is the name of the server component you want to call, ie Gateway.getDatetime.

parameters
This is an object of parameters you want to call the component with. (See components list for details on what parameters each component expects.)

echo
You can set this to ANY value, and it will be returned, verbatim, in the server response.

Secure Calls

Some components can use encryption (see Encryption help page) to obfuscate what gets sent over the network.

If you have encryption enabled on your Newgrounds.com Project/API Tools dashboard, you will need to convert 'call objects' to 'secure call' objects.

Secure calls have the following properties:

secure (required)
This is a regular 'call object' (see above), that has been encoded into a JSON string, encrypted using a cipher, and encoded to a hexadecimal or base64 string, depending on your encryption settings (see Getting Started page for details).

Note: You will only need to do this for components that indicate they support encryption, and only if you have encryption enabled on your Newgrounds.com Project/API Tools dashboard. Encryption is 100% optional if you are not using a pre-made library.


Putting it all together

Earlier in the page, we made a test POST using the Gateway.getDatetime component. Let's break that down using what we now know.

The call object for our post looks like this:

{
    "component": "Gateway.getDatetime",
    "parameters": {},
    "echo": "Hello World!"
}

We have defined the component we want to call (Gateway.getDatetime), and added an echo just because we can. This component does not require any parameters, so we could have left that out if we wanted.

We then wrap that call inside an input object, and end up with this:

{
    "app_id": "test",
    "debug": true,
    "call": {
        "component": "Gateway.getDatetime",
        "parameters": {},
        "echo": "Hello World!"
    }
}

Our input object is using the handy 'test' app_id, and running in debug mode.

Finally, we POST a request value named 'input', using our JSON-encoded input object as the value, to the gateway.


Handling the Server Response

In our example, at the top of the page, we posted a call to the Gateway.getDatetime component, and we should have seen the following result (or thereabouts):

{
    "success": true,
    "app_id": "test",
    "result": {
        "echo": "Hello World!",
        "component": "Gateway.getDatetime",
        "data": {
            "success": true,
            "datetime": "2016-07-29T16:33:55-04:00",
            "debug": true
        }
    },
    "debug": {
        "exec_time": 0.002817,
        "input": {
            "app_id": "39685:NJ1KkPGb",
            "debug": true,
            "call": {
                "component": "Gateway.getDatetime",
                "parameters": {},
                "echo": "Hello World!"
            }
        }
    }
}

This JSON response is what we call an 'output object'.


The Output Object

Output objects contain the results of any components that were executed and/or any errors that may have occurred.

Output objects may have the following properties:

success (always)
If this is true, you were successful in posting to the gateway, and should have a result object.

app_id
The App ID that was used in your 'input object'.

error (if success is false)
This will be an object with 2 properties: code and message. These objects contain information about anything that may have gone wrong.

api_version (if success is false)
If there was a problem, the server will let you know what version it is at in case you've hit a deprecation issue.

result (if success is true)
This will be a 'result object'(See 'The Result Object' below) or an array of multiple result objects if you used an array as your input object's 'call' property.

echo
If your 'input object' had an echo value, this will be exactly the same.

debug
If your 'input object' had debug set to true, this object will contain an 'exec_time' value indicating how long it took the component to run, and an 'input' value containing a copy of the 'input object' you posted.

In our example, the success property of is true, and we have a....


The Result Object

Result objects are the counterpart of call objects. They contain information about what the component returned.

A result object will have the following properties:

component (always)
This will be the name of the component that was called.

data
The results from the component. This object will always have a 'success' value. If 'success' is true, it will also contain all of the expected properties associated with the component that was called. If 'success' is false, it will also have an 'error' object with 'code' and 'message' values. If the component was called in debug mode, there will also be a debug property.

In our example post, we received a successful result with a 'data' value of:

"data": {
    "success": true,
    "datetime": "2016-07-29T16:33:55-04:00",
    "debug": true
}

We know it worked because 'success' is true, and we received the expected 'datetime' value!

Check the components list page for details on what each component will return in these 'data' objects.


Multitasking

To help keep your games snappy, you can call up to 10 components in a single post. This is done by using an array as the 'call' value in your 'input object'.

Let's look at two separate calls, and what they return:

Calling Gateway.getVersion with...

{
    "app_id": "test",
    "call": {
        "component": "Gateway.getVersion"
    }
}
...returns
{
    "success": true,
    "app_id": "test",
    "result": {
        "component": "Gateway.getVersion",
        "data": {
            "success": true,
            "version": "3.0.0"
        }
    }
}

And calling Gateway.getDatetime with...

{
    "app_id": "test",
    "call": {
        "component": "Gateway.getDatetime"
    }
}
...returns
{
    "success": true,
    "app_id": "test",
    "result": {
        "component": "Gateway.getDatetime",
        "data": {
            "success": true,
            "datetime": "2016-07-29T17:37:24-04:00"
        }
    }
}

In both examples, the 'call' property and corresponding 'result' property are flat objects.

By using an array in the 'call' property (to call BOTH components) like so...

{
    "app_id": "test",
    "call": [
        {
            "component": "Gateway.getVersion"
        },{
            "component": "Gateway.getDatetime"
        }
    ]
}
... we get an array back in the 'result' property:
{
    "success": true,
    "app_id": "test",
    "result": [
        {
            "component": "Gateway.getVersion",
            "data": {
                "success": true,
                "version": "3.0.0"
            }
        },
        {
            "component": "Gateway.getDatetime",
            "data": {
                "success": true,
                "datetime": "2016-07-29T17:37:24-04:00"
            }
        }
    ]
}


Request Throttling

In the past, developers have accidentally put calls to the server in a bad loop which resulted in 1000s of requests per second.

To make sure our servers remain as stable as possible, and to help you catch similar loops in your code if they happen, we have implemented some throttling measures.

If your app starts making too many calls, too fast, the gateway will start by returning some errors explaining what is happening. It will then temporarily block your app from making additional calls.

If you find your game is having problems making calls to the server, this is probably the first thing you should investigate.

Our throttling thresholds are set very high, so if your game is working optimally, you will probably never have to deal with this.