Posting to the Gateway

All calls to the API are done by posting to the Newgrounds.io Gateway at https://www.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 request.

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

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

Click here to test the POST method

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

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

{ "app_id": "test", "debug": true, "execute": { "component": "Gateway.getDatetime", "parameters": {}, "echo": "Hello World!" } }
Click here to POST the above JSON object

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

The gateway expects requests objects to be sent one of 2 ways. Either send the raw JSON string as your request, or POST it as a form in a variable called 'request', as shown above (application/x-www-form-urlencoded).

---

The Request Object

As explained above, the gateway script will always expect a request 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 execute.

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

---

The Execute Object

The execute object defines which component to run, and what parameters to call it with.

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

Secure Executions

Some components 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 (this is enabled by default), you will need to secure any execute objects you want to send.

To do this, simply take the JSON string representing your component, and encrypt it using the cypher your project is set to use (128 bit AES is the default), then encode that with whichever encoder you are set to use (Base 64 is the default).

A secure execute object only has a single property:

Note: You can send ANY component securely, but you 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 execute 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 property out if we wanted.

We then wrap the execute object inside a request object, and end up with this:

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

If we wanted to send this as a secure call, it would look like this:

{
    "app_id": "test",
    "debug": true,
    "execute": {
        "secure": "6Fp\/AK4biFxcLMKnaCMIVxeEusQOf3BlIUGYEIPlTbN4k+NJB3AtNRROu40kFaYVrSBVkSTtWB\/qM1DrT3kUGYvluc+9bx\/4oKE0wilzhyo2ygfFyMPhR0hDLE3Fu22k"
    }
}

And that's it! You can now post this object to the gateway using the POST method, and you should receive a response object in return.

Note: You can either post the raw JSON object (using something like JavaScript's fetch method), or you can POST as a form by assigning the json string to a variable called 'request' (using something like JavaScript's XMLHttpRequest).

---

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,
        "request": {
            "app_id": "39685:NJ1KkPGb",
            "debug": true,
            "execute": {
                "component": "Gateway.getDatetime",
                "parameters": {},
                "echo": "Hello World!"
            }
        }
    }
}

This JSON response is what we call a 'response object'.

---

The Response Object

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

Response objects may have the following properties:

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

---

The Result Object

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

A result object will have the following properties:

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.

---

Error Objects

In the event a Response or Result object has a 'success' value of false, there will also be an 'error' value (see Error Object).

This value will be directly in Response Objects, or inside the 'data' value of Result Objects.

This object will have a 'message' value explaining the error in a string format, and an integer 'code' value that represents the broader error type.

---

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 'execute' value in your 'request 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 'execute' 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",
    "execute": [
        {
            "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"
            }
        }
    ]
}

You can also send arrays of secure execute objects or mix plain objects with secure ones.

---

Request Spamming

Because many users of the Newgrounds.io API are novices, we have taken measures to handle things like bad loops, excessive packet sizes, and so on. If your app spams our gateway, it will be treated like any other DDOS attack, and the end user will be blocked.

For this reason, we strongly encourage you to only make API calls when they are necessary (you don't need to save your game, or post your current score on every single iteration of your game loop!).