#Fundamentals

This page has the information you need when working with our API. It covers the basics of what API is, what is REST API, what is JSON, how to work with files, and other useful information.

If you are looking for information on how to use a specific endpoint, you can find all the endpoints in the References section in the menu on the left.

#Table of Contents

• What is an API?
• What is REST API?
• What is HTTP?
  • HTTP Request
  • HTTP Response
  • HTTP methods
• What is JSON?
• API versioning
• Deprecated endpoints
• Request and response structures
  • Request structure
    • Request body structure
    • Request parameters
    • Request query parameters
  • Response structure
    • Successful response structure
    • Unsuccessful response structure
• Bulk requests
• Authentication
• Access Control List
• Error codes

#What is an API?

API stands for Application Programming Interface. It is a set of clearly defined methods of communication between various software components. An API makes it easier to develop computer programs by providing all the building blocks, which are then put together by the programmer.

#What is REST API?

Teltonika Networks API is based on RESTful principles and uses JSON as a data format. REST stands for Representational State Transfer. It relies on a stateless, client-server, cacheable communications protocol — and in virtually all cases, the HTTP protocol is used. REST APIs are designed around resources, which are any kind of object, data, or service that can be accessed by the client. The main principle of REST is that everything is a resource and each resource is accessible via a unique URI (Uniform Resource Identifier).

#What is HTTP?

HTTP stands for Hypertext Transfer Protocol. It’s a stateless, application-layer protocol for communicating between distributed systems, and is the foundation of the modern web. HTTP works as a request-response protocol between a client and server.

When a client, usually a web browser, makes a request to a server the following process occurs:

1. A TCP connection is opened.
2. The request is sent over the connection.
3. The server handles the request.
4. The server sends back a response.
5. The connection is closed.

The request and response between the client and server are made up of two parts: the header and the body.

#HTTP Request

The HTTP request header contains information about the request, such as the HTTP method used (GET, POST, PUT, DELETE, etc.), the requested URL, and more.

The HTTP request body contains the data that needs to be sent to the server, for example, when you’re creating or updating a resource.

#HTTP Response

The HTTP response header contains information about the response, like the HTTP version, the status code, and more.

The HTTP response body contains the data that needs to be sent back to the client, for example, when you’re returning a resource.

#HTTP methods

The following HTTP methods can be used to perform actions on resources:

#What is JSON?

JSON stands for JavaScript Object Notation. JSON is a lightweight format for storing and transporting data. JSON is often used when data is sent from a server to a web page. It is used to send and receive data in our API.

#API versioning

The API is versioned, this means that each version of the API is available under a specific URL. To access a specific API version, prefix all endpoints with /api/v1/.

For example, to access the /system/device/status endpoint, you need to send a request to /api/v1/system/device/status.

If you don’t specify a version, the latest version of the API will be used.

#Deprecated endpoints

Some endpoints or their properties are deprecated and are no longer supported. They are marked with a DEPRECATED badge.

Usage of deprecated endpoints is not recommended, use at your own risk.

#Request and response structures

The API is created by following RESTful principles and it’s based on the OpenAPI 3.0 specification with custom extensions prefixed by x-, such as x-web.

#Request structure

Example of a typical request to an API endpoint:

{
    "method": "POST",
    "url": "/api/example/endpoint",
    "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer <AUTH_TOKEN>"
    },
    "body": {
        "data": {
            "some_data": "example"
        }
    }
}

The request structure can contain these properties:

#Request body structure

The default request body structure usually contains these properties:

Details about request body structure for each endpoint can be found in the References section in the menu on the left.

#Request parameters

Some endpoints require you to include a parameter in the URL. For example, to get information about a specific user, you need to send a request to GET /api/users/config/{id} with {id} replaced with the user ID.

#Request query parameters

Some endpoints allow you to optionally include query parameters in the URL. To specify query parameters, append them to the URL after a ? character in the form of key-value pairs, separated by &. For example, to get the last 5 system event logs, make a request to GET /api/events_log/config/system?limit=5.

#Response structure

Responses from an API endpoint are always either successful or unsuccessful. Successful responses contain the data you requested, while unsuccessful responses contain details about what went wrong.

#Successful response structure

Example of a successful response from an API endpoint:

{
    "success": true,
    "data": [
        {
            "username": "admin",
            "group": "root"
        }
    ]
}

A successful response contains these properties:

Successful responses respond with HTTP status code in the range of 200-207.

#Unsuccessful response structure

Example of an unsuccessful response from an API endpoint:

{
    "success": false,
    "errors": [
        {
            "code": 106,
            "error": "Generation of backup failed.",
            "source": "Validation",
            "section": "generate_backup"
        }
    ]
}

An unsuccessful response contains:

Errors array contains objects with the following properties:

Unsuccessful responses respond with HTTP status code in the range of 400-422.

#Bulk requests

Bulk requests allow you to send multiple requests to different endpoints in a single HTTP request. This can be useful when you need to perform multiple actions at once.

To perform a bulk request, send a request to POST /api/bulk endpoint with the body including the property data of an array of objects with the following properties:

For example, if you need to create multiple users, instead of sending multiple requests to POST /api/users/config endpoint, you can send a single request to POST /api/bulk endpoint with the following body:

{
    "data": [
        {
            "endpoint": "/api/users/config",
            "method": "POST",
            "data": {
                "username": "user1",
                "password": "Password1",
                "group": "admin"
            }
        },
        {
            "endpoint": "/api/users/config",
            "method": "POST",
            "data": {
                "username": "user2",
                "password": "Password2",
                "group": "user"
            }
        }
    ]
}

Example of a response to the above bulk request:

{
    "success": true,
    "data": [
        {
            "success": true,
            "data": {
                "username": "user1",
                ".type": "login",
                "id": "cfg07f8be",
                "group": "admin"
            }
        },
        {
            "success": true,
            "data": {
                "username": "user2",
                ".type": "login",
                "id": "cfg08f8be",
                "group": "user"
            }
        }
    ]
}

#Authentication

Each session token is valid for 5 minutes after which you will need to authenticate again. To authenticate, send a request to POST /api/login endpoint with the following properties included in the body:

Example of a request to the POST /api/login endpoint:

{
    "method": "POST",
    "url": "/api/login",
    "headers": {
        "Content-Type": "application/json"
    },
    "body": {
        "data": {
            "username": "admin",
            "password": "admin"
        }
    }
}

If the login was successful, the response will contain the following properties:

Example of a successful response to the above login request:

{
    "success": true,
    "data": {
        "username": "admin",
        "token": "3293....9d66",
        "expires": 299
    }
}

#Access Control List

Access control list (ACL) is an object that contains a list of endpoints that the authenticated user is allowed to access. Each endpoint is assigned a list of actions that the user is allowed to perform on the endpoint.

Example of an ACL for API endpoints:

{
    "api": {
        "/device/*": [
            "read"
        ],
        "/logging/*": [
            "read",
            "write"
        ]
    }
}

The above ACL allows the user to make GET requests to all endpoints that start with /device/ and GET and POST requests to all endpoints that start with /logging/.

To check if the authenticated user is allowed to access a specific endpoint, you need to check if the endpoint is included in the ACL.

Users with root group have access to all endpoints.

To change access for a group, use the PUT /api/users/groups/config endpoint.

Relation between HTTP methods and read and write actions:

#Error codes

Below are listed all the possible error codes that could be included within error objects described here.