API Endpoints

🌐 API Endpoints

This section provides details about the PrevNames API endpoints, which allow you to retrieve user name history and stream real-time name change events.

---

1. Get User Name History

Endpoint

GET /api/users/:userId/prevnames

Description

This endpoint retrieves the history of username and display name changes for a specific Discord user.

Parameters

Parameter	Type	Description
userId	String	The Discord user ID (required). This is the unique identifier of the user whose name history you want to fetch.

Request Example

To get the name history of a specific user, replace :userId with the actual Discord user ID in the URL:

GET /api/users/123456789012345678/prevnames

Response Example

The response will return a JSON object containing the user’s name change history. The prevnames array will include the previous usernames and display names, along with the timestamps of each change.

{
  "userId": "123456789012345678",
  "prevnames": [
    {
      "type": "username",
      "name": "kirby",
      "changedAt": "2024-06-07T15:30:00Z"
    },
    {
      "type": "displayname",
      "name": "kirbyy uwu",
      "changedAt": "2024-07-01T12:15:00Z"
    }
  ],
  "code": 200
}

Response Structure

• userId: The Discord User ID.

• prevnames: An array containing the user’s previous name changes, including:

  • type: Type of change (username or displayname).

  • name: The previous name.

  • changedAt: Timestamp when the name change occurred.

• code: The status code of the response (200 for success, 500 for error).

Error Response Example

If no name history is found for the user:

{
  "userId": "123456789012345678",
  "prevnames": [],
  "code": 200
}

If an error occurs during the request:

{
  "message": "Internal server error.",
  "code": 500
}

---

2. Stream Real-Time Name Changes

Endpoint

GET /api/webhooks/prevnames/listen

Description

This endpoint allows you to listen for real-time notifications of username and display name changes. When a user’s name changes, the event will be pushed to all connected clients.

Request Example

To initiate the streaming connection, make a GET request to the /api/webhooks/prevnames/listen endpoint:

GET /api/webhooks/prevnames/listen

Once connected, the server will send events in Server-Sent Events (SSE) format whenever a name change occurs.

Response Format

The server will push new events in the following format when a name change occurs:

data: {
  "userId": "123456789012345678",
  "type": "username",
  "name": "NewUsername",
  "changedAt": "2024-12-07T08:15:00Z"
}

Each event will be delivered as an individual message under the data field.

Error Handling

If the connection is closed or there is an error:

{
  "message": "Error establishing connection.",
  "code": 500
}

---

3. Send Name Change Event

Endpoint

POST /api/webhooks/prevnames

Description

This endpoint is used to send new name change events to all active listeners connected to the /prevnames/listen stream. Whenever a user’s name changes (either username or display name), this endpoint can be triggered to notify all connected clients.

Request Body Example

When sending a name change event, use a POST request with the event data in the body:

{
  "userId": "123456789012345678",
  "type": "username",
  "name": "NewUsername",
  "changedAt": "2024-12-07T08:15:00Z"
}

Response Example

On successful delivery of the event:

{
  "success": true
}

Error Response Example

If the event could not be sent (e.g., no listeners are connected):

{
  "message": "Failed to deliver event.",
  "code": 500
}

---

Additional Notes

• Authentication: Authentication is not required for these endpoints, but you may choose to implement it in a production environment.

• Error Codes:

  • 500: Server error (e.g., connection issues, internal processing failures).

  • 200: Successful request/response.

  • If no previous names are found, an empty list will be returned with a 200 code.

• Data Persistence: The name change data is stored in a MongoDB database and can be accessed or streamed through the above endpoints.