BETA

Newgrounds.io Object Models

Much of the data the Newgrounds.io server uses exists in structured objects. Below are details on how each of these objects are modelled.


call

Contains all the information needed to execute an API component.

Properties:

component* — string
The name of the component you want to call, ie 'App.connect'.
(Only required if 'secure' is not set.)

echo — mixed
An optional value that will be returned, verbatim, in the result object.

parameters — object or array of objects
An object of parameters you want to pass to the component.

secure* — string
A an encrypted call object or array of call objects.
(Only required if 'component' is not set.)

* Required property

NOTES: For secure calls using encryption, you only need to pass the 'secure' property. For all other calls, you only need to use the 'component' and 'parameters' properties.


debug

Contains extra debugging information.

Properties:

exec_time — string
The time, in milliseconds, that it took to execute a request.

input input object
A copy of the input object that was posted to the server.

NOTES: This object is only used in debug mode.


error

Properties:

code — int
A code indication the error type.

message — string
Contains details about the error.


input

A top-level wrapper containing any information needed to authenticate the application/user and any component calls being made.

Properties:

app_id* — string
Your application's unique ID.

call* call object or array of call objects
A call object, or array of one-or-more call objects.

debug — bool
If set to true, calls will be executed in debug mode.

echo — mixed
An optional value that will be returned, verbatim, in the output object.

session_id — string
An optional login session id.

* Required property


medal

Contains information about a medal.

Properties:

description — string
A short description of the medal.

difficulty — int
The difficulty id of the medal.

icon — string
The URL for the medal's icon.

id — int
The numeric ID of the medal.

name — string
The name of the medal.

secret — boolean

unlocked — boolean
This will only be set if a valid user session exists.

value — int
The medal's point value.

NOTES: Medal Difficulties:
1 = Easy
2 = Moderate
3 = Challenging
4 = Difficult
5 = Brutal


output

Contains all return output from an API request.

Properties:

api_version — string
If there was an error, this will contain the current version number of the API gateway.

app_id — string
Your application's unique ID

debug debug object
Contains extra information you may need when debugging (debug mode only).

echo — mixed
If you passed an 'echo' value in your input object, it will be echoed here.

error error object
This will contain any error info if the success property is false.

help_url — string
If there was an error, this will contain the URL for our help docs.

result result object or array of result objects
This will be a result object, or an array containing one-or-more result objects (this will match the structure of the call property in your input object).

success — boolean
If false, there was a problem with your 'input' object. Details will be in the error property.


result

Contains information returned by an API component.

Properties:

component — string
The name of the component that was executed (ie 'Medal.unlock').

data — object or array of objects
An object, or array of one-or-more objects (follows the structure of the corresponding 'call' property), containing any returned properties or errors.

echo — mixed
If you passed an 'echo' value in your call object, it will be echoed here.

NOTES: The 'data' object will always contain a 'success' property. If the call was unsuccessful, there will also be an ' error' property.


score

Contains information about a score posted to a scoreboard.

Properties:

formatted_value — string
The score value in the format selected in your scoreboard settings.

tag — string
The tag attached to this score (if any).

user user object
The user who earned score. If this property is absent, the score belongs to the active user.

value — int
The integer value of the score.


scoreboard

Contains information about a scoreboard.

Properties:

id — int
The numeric ID of the scoreboard.

name — string
The name of the scoreboard.


session

Contains information about the current user session.

Properties:

expired — boolean
If true, the session_id is expired. Use App.startSession to get a new one.

id — string
A unique session identifier

passport_url — string
If the session has no associated user but is not expired, this property will provide a URL that can be used to sign the user in.

remember — boolean
If true, the user would like you to remember their session id.

user user object
If the user has not signed in, or granted access to your app, this will be null

NOTES: Remembered sessions will expire after 30 days of inactivity. All other sessions will expire after one hour of inactivity.

Session expirations get renewed with every call. You could use 'Gateway.ping' every 5 minutes to keep sessions alive.


user

Contains information about a user.

Properties:

icons usericons object
The user's icon images.

id — int
The user's numeric ID.

name — string
The user's textual name.

supporter — boolean
Returns true if the user has a Newgrounds Supporter upgrade.


usericons

Contains any icons associated with this user.

Properties:

large — string
The URL of the user's large icon

medium — string
The URL of the user's medium icon

small — string
The URL of the user's small icon