Net API Documentation

Introduction

Welcome to the Net API documentation. This API provides access to user management functionalities, allowing you to retrieve, create, update, and delete user data.

The API is built using RESTful principles and returns data in JSON format. All requests should be made over HTTPS.

Authentication

All requests to the Net API require authentication. You must include an API key in theAuthorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

If you do not have an API key, please contact your administrator.

Endpoints

GET /users

Retrieves a list of all users.

Optional Query Parameters:

  • limit (integer): The maximum number of users to return.
  • offset (integer): The number of users to skip before starting to collect the result set.

Request Example:

GET /users?limit=10&offset=0 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Response Example (200 OK):

[
  {
    "id": "1a2b3c4d",
    "username": "alice",
    "email": "alice@example.com",
    "createdAt": "2023-10-27T10:00:00Z"
  },
  {
    "id": "5e6f7g8h",
    "username": "bob",
    "email": "bob@example.com",
    "createdAt": "2023-10-27T10:05:00Z"
  }
]

GET /users/{id}

Retrieves a specific user by their unique ID.

Path Parameters:

Name Type Description Required
id string The unique identifier of the user. Yes

Request Example:

GET /users/1a2b3c4d HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Response Example (200 OK):

{
  "id": "1a2b3c4d",
  "username": "alice",
  "email": "alice@example.com",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T11:30:00Z"
}

Response Example (404 Not Found):

{
  "error": "User not found",
  "message": "No user with the ID 'nonexistent-id' could be found."
}

POST /users

Creates a new user.

Request Body (JSON):

Name Type Description Required
username string The desired username for the new user. Must be unique. Yes
email string The email address for the new user. Must be unique and valid format. Yes
password string The password for the new user. Minimum 8 characters. Yes

Request Example:

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "username": "charlie",
  "email": "charlie@example.com",
  "password": "securePassword123"
}

Response Example (201 Created):

{
  "id": "9i10j11k",
  "username": "charlie",
  "email": "charlie@example.com",
  "createdAt": "2023-10-27T11:45:00Z"
}

Response Example (400 Bad Request):

{
  "error": "Bad Request",
  "message": "Username 'charlie' already exists."
}

PUT /users/{id}

Updates an existing user by their unique ID.

Path Parameters:

Name Type Description Required
id string The unique identifier of the user to update. Yes

Request Body (JSON):

You can optionally provide any of the user's properties to update.

Name Type Description Required
email string The new email address for the user. Must be unique and valid format. No
password string The new password for the user. Minimum 8 characters. No

Request Example:

PUT /users/1a2b3c4d HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "email": "alice.updated@example.com"
}

Response Example (200 OK):

{
  "id": "1a2b3c4d",
  "username": "alice",
  "email": "alice.updated@example.com",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T12:00:00Z"
}

Response Example (404 Not Found):

{
  "error": "User not found",
  "message": "No user with the ID '1a2b3c4d' could be found."
}

DELETE /users/{id}

Deletes a user by their unique ID.

Path Parameters:

Name Type Description Required
id string The unique identifier of the user to delete. Yes

Request Example:

DELETE /users/5e6f7g8h HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Response Example (204 No Content):

A 204 No Content response indicates the user was successfully deleted.

Response Example (404 Not Found):

{
  "error": "User not found",
  "message": "No user with the ID '5e6f7g8h' could be found."
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses will be returned in JSON format and include an error and message field.

Common status codes include: