Network API Reference

Overview

Welcome to the Network API documentation. This API provides access to manage and retrieve network-related data. All API requests should be made to the base URL: https://api.example.com/v1.

The API uses standard HTTP methods (GET, POST, PUT, DELETE, PATCH) and returns responses in JSON format. Authentication is required for most requests.

Authentication

API requests are authenticated using API keys. Include your API key in the Authorization header of your request as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Obtain your API key from your account settings.

Resources

Users

Manage user accounts and profiles.

List Users

GET /users

Retrieves a list of all users.

Query Parameters
Name Type Description Required
limit integer Maximum number of users to return. No
offset integer Number of users to skip before starting to collect the result set. No
Response Example (200 OK)
{
  "data": [
    {
      "id": "user_abc123",
      "username": "alice",
      "email": "alice@example.com",
      "created_at": "2023-10-26T10:00:00Z"
    },
    {
      "id": "user_def456",
      "username": "bob",
      "email": "bob@example.com",
      "created_at": "2023-10-26T10:05:00Z"
    }
  ],
  "total": 2,
  "limit": 10,
  "offset": 0
}

Get User by ID

GET /users/{user_id}

Retrieves a specific user by their ID.

Path Parameters
Name Type Description Required
user_id string The unique identifier of the user. Yes
Response Example (200 OK)
{
  "id": "user_abc123",
  "username": "alice",
  "email": "alice@example.com",
  "created_at": "2023-10-26T10:00:00Z",
  "status": "active"
}

Create User

POST /users

Creates a new user account.

Request Body
{
  "username": "charlie",
  "email": "charlie@example.com",
  "password": "securepassword123"
}
Response Example (201 Created)
{
  "id": "user_ghi789",
  "username": "charlie",
  "email": "charlie@example.com",
  "created_at": "2023-10-27T09:30:00Z",
  "status": "pending_verification"
}

Products

Information about available network products.

List Products

GET /products

Retrieves a catalog of available network products.

Query Parameters
Name Type Description Required
category string Filter products by category. No
Response Example (200 OK)
{
  "data": [
    {
      "id": "prod_router_001",
      "name": "Enterprise Router X1",
      "description": "High-performance router for large enterprises.",
      "category": "routers",
      "price": 1200.00
    },
    {
      "id": "prod_switch_005",
      "name": "Managed Switch S500",
      "description": "24-port managed switch with PoE.",
      "category": "switches",
      "price": 450.50
    }
  ]
}

Orders

Manage network service orders.

Get Order Status

GET /orders/{order_id}/status

Retrieves the current status of a specific order.

Path Parameters
Name Type Description Required
order_id string The unique identifier of the order. Yes
Response Example (200 OK)
{
  "order_id": "order_xyz789",
  "status": "processing",
  "estimated_completion": "2023-10-28T15:00:00Z",
  "updated_at": "2023-10-27T11:00:00Z"
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses will include a JSON body with more details:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The provided 'user_id' is not a valid format.",
    "details": "Expected format: 'user_...'."
  }
}

Common Status Codes:

Rate Limiting

To ensure fair usage and stability, the API enforces rate limits. You can make up to 1000 requests per minute per API key.

If you exceed the rate limit, you will receive a 429 Too Many Requests response. The response headers will include: