US01 - Criar endpoint para User Specialties

[Iewandowski]

Contrato REST API - Especialidades do Usuário

URL Base

https://api.pointtils.com/v1

Autenticação

Todos os endpoints requerem autenticação JWT. Inclua o token no cabeçalho Authorization:

Authorization: Bearer <jwt_token>

Endpoints

1. Obter Especialidades do Usuário

Recupera todas as especialidades associadas a um usuário.

Endpoint: GET /users/{userId}/specialties

Parâmetros de Caminho:

• userId (UUID) - ID do usuário

Resposta:

{
  "success": true,
  "message": "Especialidades do usuário obtidas com sucesso",
  "data": {
    "specialties": [
      {
        "id": "uuid",
        "userId": "uuid",
        "specialtyId": "uuid",
        "specialtyName": "string"
      }
    ],
    "summary": {
      "added": 5,
      "total": 5,
      "duplicatesIgnored": 0
    }
  }
}

Respostas de Erro:

• 404 Not Found - Usuário não encontrado
• 500 Internal Server Error - Erro inesperado

---

2. Adicionar Especialidades ao Usuário

Adiciona uma ou mais especialidades a um usuário.

Endpoint: POST /users/{userId}/specialties

Parâmetros de Caminho:

• userId (UUID) - ID do usuário

Corpo da Requisição:

{
  "specialtyIds": ["uuid1", "uuid2", "uuid3"],
  "replaceExisting": false
}

Resposta:

{
  "success": true,
  "message": "Especialidades adicionadas com sucesso",
  "data": {
    "specialties": [
      {
        "id": "uuid",
        "userId": "uuid",
        "specialtyId": "uuid",
        "specialtyName": "string"
      }
    ],
    "summary": {
      "added": 3,
      "total": 8,
      "duplicatesIgnored": 0
    }
  }
}

Respostas de Erro:

• 400 Bad Request - IDs de especialidade inválidos ou usuário não encontrado
• 404 Not Found - Usuário não encontrado
• 500 Internal Server Error - Erro inesperado

---

3. Substituir Especialidades do Usuário

Substitui todas as especialidades do usuário por um novo conjunto.

Endpoint: PUT /users/{userId}/specialties

Parâmetros de Caminho:

• userId (UUID) - ID do usuário

Corpo da Requisição:

["uuid1", "uuid2", "uuid3"]

Resposta:

{
  "success": true,
  "message": "Especialidades do usuário atualizadas com sucesso",
  "data": {
    "specialties": [
      {
        "id": "uuid",
        "userId": "uuid",
        "specialtyId": "uuid",
        "specialtyName": "string"
      }
    ],
    "summary": {
      "added": 3,
      "total": 3,
      "duplicatesIgnored": 0
    }
  }
}

Respostas de Erro:

• 400 Bad Request - IDs de especialidade inválidos ou usuário não encontrado
• 404 Not Found - Usuário não encontrado
• 500 Internal Server Error - Erro inesperado

---

4. Atualizar Especialidade do Usuário

Atualiza uma especialidade específica do usuário.

Endpoint: PATCH /users/{userId}/specialties/{userSpecialtyId}

Parâmetros de Caminho:

• userId (UUID) - ID do usuário
• userSpecialtyId (UUID) - ID da especialidade do usuário a ser atualizada

Parâmetros de Consulta:

• newSpecialtyId (UUID) - Novo ID da especialidade

Resposta:

{
  "id": "uuid",
  "userId": "uuid",
  "specialtyId": "uuid",
  "specialtyName": "string"
}

Respostas de Erro:

• 400 Bad Request - ID de especialidade inválido ou usuário não encontrado
• 404 Not Found - Especialidade do usuário não encontrada
• 500 Internal Server Error - Erro inesperado

---

5. Remover Especialidade do Usuário

Remove uma especialidade específica de um usuário.

Endpoint: DELETE /users/{userId}/specialties/{specialtyId}

Parâmetros de Caminho:

• userId (UUID) - ID do usuário
• specialtyId (UUID) - ID da especialidade a ser removida

Resposta: 204 No Content

Respostas de Erro:

• 404 Not Found - Usuário ou especialidade não encontrada
• 500 Internal Server Error - Erro inesperado

---

6. Remover Múltiplas Especialidades do Usuário

Remove múltiplas especialidades de um usuário.

Endpoint: DELETE /users/{userId}/specialties

Parâmetros de Caminho:

• userId (UUID) - ID do usuário

Parâmetros de Consulta:

• specialtyIds (List) - Lista de IDs de especialidades a serem removidas

Resposta:

{
  "success": true,
  "message": "Especialidades removidas com sucesso",
  "data": {
    "specialties": null,
    "summary": {
      "added": 0,
      "total": 5,
      "duplicatesIgnored": 0
    }
  }
}

Respostas de Erro:

• 400 Bad Request - IDs de especialidade inválidos ou usuário não encontrado
• 404 Not Found - Usuário não encontrado
• 500 Internal Server Error - Erro inesperado

---

Tipos de Dados

Formato UUID

Todos os UUIDs devem estar no formato padrão:

123e4567-e89b-12d3-a456-426614174000

Objeto Especialidade

{
  "id": "uuid",
  "userId": "uuid",
  "specialtyId": "uuid",
  "specialtyName": "string"
}

Objeto Sumário

{
  "added": 5,
  "total": 5,
  "duplicatesIgnored": 0
}

Formato de Resposta de Erro

{
  "success": false,
  "message": "Descrição da mensagem de erro",
  "data": null
}

Códigos de Status

• 200 OK - Requisição bem-sucedida
• 201 Created - Recurso criado com sucesso
• 204 No Content - Requisição bem-sucedida, sem conteúdo para retornar
• 400 Bad Request - Parâmetros de requisição inválidos
• 401 Unauthorized - Autenticação necessária ou inválida
• 403 Forbidden - Permissões insuficientes
• 404 Not Found - Recurso não encontrado
• 500 Internal Server Error - Erro do servidor

Limitação de Taxa

• Máximo 100 requisições por minuto por endereço IP
• Máximo 1000 requisições por hora por usuário

Versionamento

Esta API é a versão 1. Todos os endpoints são prefixados com /v1/.

Exemplos de Uso

Exemplo 1: Adicionar especialidades

curl -X POST "https://api.pointtils.com/v1/users/123e4567-e89b-12d3-a456-426614174000/specialties" \
  -H "Authorization: Bearer seu_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "specialtyIds": ["456e7890-f12c-34d5-b678-901234567890", "789f0123-g45h-67i8-j901-234567890123"],
    "replaceExisting": false
  }'

Exemplo 2: Obter especialidades

curl -X GET "https://api.pointtils.com/v1/users/123e4567-e89b-12d3-a456-426614174000/specialties" \
  -H "Authorization: Bearer seu_jwt_token"

Exemplo 3: Remover especialidade

curl -X DELETE "https://api.pointtils.com/v1/users/123e4567-e89b-12d3-a456-426614174000/specialties/456e7890-f12c-34d5-b678-901234567890" \
  -H "Authorization: Bearer seu_jwt_token"