Skip to content

Latest commit

 

History

History
210 lines (159 loc) · 8.44 KB

participants.md

File metadata and controls

210 lines (159 loc) · 8.44 KB

REST API Documentation for Participants

Table of Contents

Endpoint: PUT /participants

Permite actualizar la información del participante autenticado actual. Este endpoint permite modificar datos del perfil como el nombre, biografía, redes sociales, etiquetas de la comunidad, entre otros. This endpoint requires authentication. See the authentication documentation for details on how to authenticate your requests.

Authentication Required: Este endpoint requiere autenticación.

Request Body

El cuerpo de la petición debe ser un objeto JSON que se ajusta al esquema RequestParticipantSchema.

export const RequestParticipantSchema = z.object({
  name: z.string(),
  bio: z.string().optional(),
  labels: z.array(z.string()),
  country: z.string().optional(),
  social: z
    .object({
      linkedin: z.string().url().optional(),
      github: z.string().url().optional(),
      twitter: z.string().url().optional(),
      website: z.string().url().optional(),
    })
    .optional(),
});

El esquema completo RequestParticipantSchema se puede encontrar en el archivo src/participants/dtos/request-participant.dto.ts (o similar).

Donde:

  • name: Nombre del participante. Tipo: string.
  • bio: Biografía o descripción del participante. Tipo: string, opcional.
  • labels: Etiquetas o categorías asociadas al participante dentro de la comunidad. Tipo: array de strings.
  • country: País de residencia del participante. Tipo: string, opcional.
  • social: Objeto que contiene enlaces a redes sociales del participante. Tipo: object, opcional.
    • linkedin: URL del perfil de LinkedIn. Tipo: string, URL válida, opcional.
    • github: URL del perfil de GitHub. Tipo: string, URL válida, opcional.
    • twitter: URL del perfil de Twitter. Tipo: string, URL válida, opcional.
    • website: URL del sitio web personal o profesional. Tipo: string, URL válida, opcional.

Example Request Body

{
  "name": "John Doe",
  "bio": "Apasionado desarrollador web.",
  "labels": ["developer", "javascript", "react"],
  "country": "Argentina",
  "social": {
    "linkedin": "https://www.linkedin.com/in/johndoe",
    "github": "https://github.com/johndoe",
    "twitter": "https://twitter.com/johndoeDev",
    "website": "https://johndoe.dev"
  }
}

Success Response

Si la información del participante se actualiza correctamente, el servicio responderá con un código de estado HTTP 200 OK.

Status Code: 200 OK

El cuerpo de la respuesta, en caso de ser necesario, contendrá la representación actualizada del perfil del participante. (Nota: No se especificó si se retorna un body en la respuesta exitosa, se asume que podría retornar el objeto actualizado o un mensaje de éxito).

Endpoint: GET /participants

Permite obtener una lista paginada de los participantes existentes en la plataforma.

Success Response

Si la petición es exitosa, el servicio responderá con un código de estado HTTP 200 OK.

Status Code: 200 OK

El cuerpo de la respuesta contendrá un objeto JSON con la siguiente estructura:

{
  "data": [
    // Array de objetos Participant (estructura del perfil del participante)
    // ...
  ],
  "nextToken": "string" // Token para la siguiente página de resultados (opcional)
}

Donde:

  • data: Un array de objetos, donde cada objeto representa un participante. La estructura de cada objeto dentro del array data se define por el ParticipantSchema.
  • nextToken: Un string opcional. Si existe más de una página de resultados, este campo contendrá un token que se puede utilizar en la siguiente petición GET a /participants para obtener la siguiente página de participantes. Si no hay más páginas, este campo no estará presente o será null.

Paginación

Para obtener la siguiente página de resultados, se debe incluir el valor del nextToken recibido en la respuesta anterior como un query parameter en la siguiente petición GET a /participants.

Por ejemplo, si la respuesta anterior contiene "nextToken": "abc123xyz", la siguiente petición para obtener la siguiente página sería:

GET /participants?nextToken=abc123xyz

Endpoint: GET /participants/:participantId

Permite obtener la información de un participante específico, utilizando su participantId.

Success Response

Si el participante con el participantId proporcionado existe, el servicio responderá con un código de estado HTTP 200 OK.

Status Code: 200 OK

El cuerpo de la respuesta contendrá un objeto JSON representando el participante solicitado, con la estructura definida por el ParticipantSchema.

Error Response

Si no se encuentra un participante con el participantId proporcionado en la base de datos, el servicio responderá con un código de estado HTTP 404 Not Found.

Status Code: 404 Not Found

Schemas

RequestParticipantSchema

Esquema utilizado como body de la petición para actualizar la información del participante autenticado en el endpoint PUT /participants. Se define en el archivo src/participants/dtos/request-participant.dto.ts (o similar).

export const RequestParticipantSchema = z.object({
  name: z.string(),
  bio: z.string().optional(),
  labels: z.array(z.string()),
  country: z.string().optional(),
  social: z
    .object({
      linkedin: z.string().url().optional(),
      github: z.string().url().optional(),
      twitter: z.string().url().optional(),
      website: z.string().url().optional(),
    })
    .optional(),
});
  • name: Nombre del participante. Tipo: string.
  • bio: Biografía o descripción del participante. Tipo: string, opcional.
  • labels: Etiquetas o categorías asociadas al participante dentro de la comunidad. Tipo: array de strings.
  • country: País de residencia del participante. Tipo: string, opcional.
  • social: Objeto que contiene enlaces a redes sociales del participante. Tipo: object, opcional.
    • linkedin: URL del perfil de LinkedIn. Tipo: string, URL válida, opcional.
    • github: URL del perfil de GitHub. Tipo: string, URL válida, opcional.
    • twitter: URL del perfil de Twitter. Tipo: string, URL válida, opcional.
    • website: URL del sitio web personal o profesional. Tipo: string, URL válida, opcional.

ParticipantSchema

Esquema que define la estructura de un participante, retornado en las respuestas de los endpoints, por ejemplo en el endpoint GET /participants. Se define en el archivo src/participants/dtos/participant.dto.ts (o similar).

export const ParticipantSchema = z.object({
  uid: z.string(),
  name: z.string(),
  bio: z.string().optional(),
  labels: z.array(z.string()),
  country: z.string().optional(),
  social: z
    .object({
      linkedin: z.string().url().optional(),
      github: z.string().url().optional(),
      twitter: z.string().url().optional(),
      website: z.string().url().optional(),
    })
    .optional(),
  updatedAt: z.string().datetime(),
});
  • uid: Identificador único del participante. Tipo: string.
  • name: Nombre del participante. Tipo: string.
  • bio: Biografía o descripción del participante. Tipo: string, opcional.
  • labels: Etiquetas o categorías asociadas al participante dentro de la comunidad. Tipo: array de strings.
  • country: País de residencia del participante. Tipo: string, opcional.
  • social: Objeto que contiene enlaces a redes sociales del participante. Tipo: object, opcional.
    • linkedin: URL del perfil de LinkedIn. Tipo: string, URL válida, opcional.
    • github: URL del perfil de GitHub. Tipo: string, URL válida, opcional.
    • twitter: URL del perfil de Twitter. Tipo: string, URL válida, opcional.
    • website: URL del sitio web personal o profesional. Tipo: string, URL válida, opcional.
  • updatedAt: Fecha y hora de la última actualización del perfil del participante. Tipo: string, formato datetime.