API Introduction

Welcome to the Net API documentation. This API allows you to programmatically interact with the Net platform to manage your network resources, retrieve data, and automate tasks.

Our API is built around RESTful principles, using standard HTTP methods (GET, POST, PUT, DELETE) and JSON for data exchange. We aim to provide a clear, consistent, and predictable interface for developers.

Key Concepts

Before diving into specific endpoints, familiarize yourself with these core concepts:

Resources: The primary objects you'll interact with, such as Devices, Networks, and Users.
Endpoints: Specific URLs that represent these resources or actions.
Requests: Your interaction with the API, including the HTTP method, URL, headers, and body.
Responses: The API's reply, containing data, status codes, and headers.
Authentication: How you prove your identity to access the API.

Base URL

All API requests should be made to the following base URL:

https://api.example.com/v1

Where v1 indicates the current version of the API.

Data Format

The API exclusively uses JSON for request and response bodies. Ensure that your requests have the Content-Type: application/json header set when sending data.

Example JSON structure:

{
    "key": "value",
    "number": 123,
    "boolean": true,
    "array": [1, 2, 3],
    "object": {
        "nested_key": "nested_value"
    }
}

Common Headers

In addition to Content-Type, the following headers are commonly used:

Authorization: Bearer <YOUR_API_KEY>: Used for authenticating your requests.
Accept: application/json: Indicates that you expect a JSON response (though this is the default).

Rate Limiting

To ensure fair usage and stability, the API employs rate limiting. You can find your current rate limit status in the response headers:

X-RateLimit-Limit: The maximum number of requests you can make in the current window.
X-RateLimit-Remaining: The number of requests remaining in the current window.
X-RateLimit-Reset: The time (in Unix epoch seconds) when the rate limit window resets.

If you exceed the rate limit, you will receive a 429 Too Many Requests status code.

Versioning

The API is versioned to allow for evolution without breaking existing integrations. The version number is included in the URL, e.g., /v1/.

We strive to maintain backward compatibility, but breaking changes will be introduced in new major versions. Please monitor our release notes for updates.

Continue to the Authentication section to learn how to secure your API calls.