API

From DAST Docs
Jump to: navigation, search

General API info

API Token

Warning: This parameter is always required to make a successful request.

Warning: We don't provide any API tokens to public at the moment.

General info

This token allows you to make API requests on our servers. Without this valid token you won't be able to execute any API requests. API token is string with length of 128 characters, each token is linked to a user account - you can find API tokens linked to your account on this page.

Usage

The api_token parameter is specified by query parameter ?api_token=YOUR_API_TOKEN in request URL. Token-User link is verified everytime token is used. Token verification can fail in these cases:

  • Account owning the token has been banned
  • User/Admin has disabled the token
  • Token has expired (tokens do not expire by default)

User Token

Warning: This parameter is only required on specific endpoints!

General info

User tokens are used to make changes to objects owned/managed by someone - to make sure, that you are allowed to make these changes and that you have valid permissions from object owner/moderator/etc. you will have to provide these tokens on specific endpoints. User token is also string with length of 128 characters just like API Token, each token is linked to a user account - you can find and generate your user tokens on this page.

Usage

The user_token parameter is specified by query parameter &user_token=USER_TOKEN (using & because there will always be API Token starting with ?. Only one user token may be specified in a single request.

Request

Structure

Below you can see request URL example and it's structure:

http://dayz-ast.com/api/home/default?api_token=YOUR_API_TOKEN&user_token=USER_TOKEN&var1=false&var2=13
Base Endpoint Action Parameters
API Token User Token (if required) Request variables
http://dayz-ast.com/api /home /default  ?api_token=YOUR_API_TOKEN &user_token=USER_TOKEN &var1=false&var2=13

Base

Base URL path for API requests is always going to be the one displayed below. This URL is going to be the same for each request to whatever endpoint you choose. When this URL would change, it would be changed globaly again - for each endpoint and action - in this case, we will always make an announcement about these upcomming changes!

http://dayz-ast.com/api/

Endpoint

Endpoint is controller which has number of actions under it. Endpoint is not callable itself (you can not make request to JUST endpoint, even when action is not specified - default action is called). There are currently these available endpoints:

Action

Action is method which is called on specific endpoint - each endpoint has it's own actions. This method processes your request and acts based on it's purpose and documentation.

Parameters

Variables required or processed by endpoint action or used to authenticate user.

Required

These parameters are globally required to ensure functionality. You have to specify them in every request made. These parameters are:

Action-specific

These parameters can be required by endpoint action or can be optional. These can be:

  • User Token
  • Identifiers
  • By-action required data
  • etc.

Response

Structure

Below you can see API response template. This template is strictly followed by API on every existing endpoint.

{
    "data": [],
    "error": [
        {
            "exception": "App\\ApiModule\\AuthException",
            "message": "Auth key parameter is missing.",
            "code": 400
        }
    ],
    "success": false
}

Response consists of 3 default properties:

This layout is consistent at any time, all data returned by API endpoint (response data) are returned to data property. Structure of returned data is further specified on each endpoint (contents of data property are variable everytime) - some endpoints may even return empty responses (data property).

Data

This is how does data property look like:

"data": []|{...}

This property contains all data returned by script. It's structure is variable and is described in endpoint action's documentation. data property can be empty in two cases:

  1. Script was processed successfully but did not return any data
  2. Error was encountered (in this case, data property is always empty)
Property values and structure
Property name Data type Possible values Value occurrence
data array empty Nothing was returned by script or error was encountered
object specified in endpoint action documentation Request was successfully processed and script returned data

Error

This is how does error property look like:

"error": [
    {
        "exception": "App\\ApiModule\\AuthException",
        "message": "Auth key parameter is missing.",
        "code": 400
    }
]

When error is encountered during processing your request it is passed to error property, it is possible to have multiple errors logged simultaneously in this property. error property contains array of exception objects (exception object structure is described below).

Property values and structure
Property name Data type Description
exception string This property contains exception's namespace
message string Message property contains further info about why does this exception occured
code integer Internal error code/HTTP Status Code

State

This is how does success property look like:

"success": true|false

This property displays overall request result, if an error was encountered during your request and request could not be completed, this variable is set to false and at this time data property is always empty. When everything worked out correctly and your request had been successfully processed by server, this variable is set to true - but this does not mean, that data property contains something - returned data are described separately for each endpoint action (endpoint actions are not forced to return any values by default).

This property only describes if request was processed successfully.

Property values and structure
Property name Data type Possible values Value occurrence
success bool true Request was successfully process
false Error(s) were encountered during request processing

Example

Below you will find some brief examples of what API response looks like.

Successful

This is successful request:

{
    "data": {...},
    "error": [],
    "success": true
}

data property is object and contains endpoint action specific values returned by script (might be empty array when nothing is returned by script)
error property is empty array, no error was encountered during request processing
success property is boolean true, no error was encountered during request processing

Unsuccessful

This is unsuccessful request (API token was not specified):

{
    "data": [],
    "error": [
        {
            "exception": "App\\ApiModule\\AuthException",
            "message": "API token parameter is missing.",
            "code": 400
        }
    ],
    "success": false
}

data property is empty array because error was encountered during request processing
error property is array containing one error object with brief description (no api_token was specified)
success property is boolean false, error was encountered during request processing