Skip to content

emanuel-malungo/Eleva

BranchesTags

Repository files navigation

API Documentation - Eleva App

Visão Geral

A API do Eleva é uma plataforma RESTful para compartilhamento de frases motivacionais e inspiradoras. Permite aos usuários criar, compartilhar, curtir e salvar conteúdo motivacional com uma comunidade engajada.

Base URL: https://api.eleva.com/v1

Autenticação: Bearer Token (JWT)

🔐 Autenticação

POST /auth/register

Registra um novo usuário na plataforma.

Request Body:

{
  "name": "Maria Santos",
  "email": "maria@exemplo.com",
  "password": "senhaSegura123"
}

Response (201):

{
  "user": {
    "id": "usr_12345",
    "name": "Maria Santos",
    "email": "maria@exemplo.com",
    "username": "mariasantos",
    "avatar_url": null,
    "created_at": "2025-03-24T10:30:00Z"
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

POST /auth/login

Autentica um usuário existente.

Request Body:

{
  "email": "maria@exemplo.com",
  "password": "senhaSegura123"
}

Response (200):

{
  "user": {
    "id": "usr_12345",
    "name": "Maria Santos",
    "email": "maria@exemplo.com",
    "username": "mariasantos",
    "avatar_url": "https://cdn.eleva.com/avatars/usr_12345.jpg",
    "stats": {
      "posts": 87,
      "likes": 3240,
      "followers": 1250,
      "following": 365
    }
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

POST /auth/refresh

Renova o token de acesso usando o refresh token.

Request Body:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

POST /auth/forgot-password

Solicita redefinição de senha.

Request Body:

{
  "email": "maria@exemplo.com"
}

POST /auth/logout

Invalida o token atual do usuário.

👤 Usuários

GET /users/me

Retorna informações do usuário autenticado.

Headers: Authorization: Bearer {token}

Response (200):

{
  "id": "usr_12345",
  "name": "Maria Santos",
  "username": "mariasantos",
  "email": "maria@exemplo.com",
  "bio": "Compartilhando inspiração diária para ajudar você a alcançar seu potencial máximo.",
  "avatar_url": "https://cdn.eleva.com/avatars/usr_12345.jpg",
  "stats": {
    "posts": 87,
    "likes": 3240,
    "followers": 1250,
    "following": 365
  },
  "preferences": {
    "privacy": "public",
    "notifications": true,
    "email_notifications": false
  },
  "created_at": "2025-01-15T08:20:00Z"
}

PUT /users/me

Atualiza informações do usuário autenticado.

Headers: Authorization: Bearer {token}

Request Body:

{
  "name": "Maria Santos Silva",
  "bio": "Nova biografia inspiradora",
  "avatar_url": "https://cdn.eleva.com/avatars/new_avatar.jpg"
}

GET /users/{user_id}

Retorna informações públicas de um usuário específico.

Response (200):

{
  "id": "usr_67890",
  "name": "João Inspirador",
  "username": "joaoinsp",
  "bio": "Motivando pessoas todos os dias",
  "avatar_url": "https://cdn.eleva.com/avatars/usr_67890.jpg",
  "stats": {
    "posts": 120,
    "likes": 4560,
    "followers": 2300,
    "following": 180
  },
  "is_following": false,
  "created_at": "2024-12-10T14:30:00Z"
}

POST /users/{user_id}/follow

Segue um usuário.

Headers: Authorization: Bearer {token}

DELETE /users/{user_id}/follow

Para de seguir um usuário.

GET /users/{user_id}/followers

Lista seguidores de um usuário.

Query Parameters:

  • page (int): Página (padrão: 1)
  • limit (int): Limite por página (padrão: 20)

GET /users/{user_id}/following

Lista usuários que o usuário está seguindo.

📝 Posts (Frases)

GET /posts

Lista posts na timeline principal.

Headers: Authorization: Bearer {token}

Query Parameters:

  • page (int): Página (padrão: 1)
  • limit (int): Limite por página (padrão: 20)
  • category (string): Filtrar por categoria
  • sort (string): Ordenação (recent, popular, trending)

Response (200):

{
  "posts": [
    {
      "id": "post_abc123",
      "quote": "Cada dia é uma nova oportunidade para mudar sua vida.",
      "author": {
        "id": "usr_12345",
        "name": "Maria Santos",
        "username": "mariasantos",
        "avatar_url": "https://cdn.eleva.com/avatars/usr_12345.jpg"
      },
      "category": {
        "id": "cat_1",
        "name": "Motivação",
        "color": "#FFD700"
      },
      "image_url": "https://cdn.eleva.com/posts/post_abc123.jpg",
      "stats": {
        "likes": 4500,
        "comments": 1200,
        "favorites": 900,
        "shares": 1800
      },
      "user_interactions": {
        "liked": true,
        "favorited": false,
        "shared": false
      },
      "created_at": "2025-03-24T09:15:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 25,
    "total_items": 500,
    "has_next": true,
    "has_prev": false
  }
}

POST /posts

Cria um novo post.

Headers: Authorization: Bearer {token}

Request Body:

{
  "quote": "A persistência é o caminho do êxito.",
  "category_id": "cat_1",
  "image_url": "https://cdn.eleva.com/uploads/temp_image.jpg",
  "settings": {
    "is_public": true,
    "allow_comments": true,
    "allow_likes": true
  }
}

Response (201):

{
  "id": "post_def456",
  "quote": "A persistência é o caminho do êxito.",
  "author": {
    "id": "usr_12345",
    "name": "Maria Santos",
    "username": "mariasantos",
    "avatar_url": "https://cdn.eleva.com/avatars/usr_12345.jpg"
  },
  "category": {
    "id": "cat_1",
    "name": "Motivação",
    "color": "#FFD700"
  },
  "image_url": "https://cdn.eleva.com/posts/post_def456.jpg",
  "stats": {
    "likes": 0,
    "comments": 0,
    "favorites": 0,
    "shares": 0
  },
  "created_at": "2025-03-24T10:45:00Z"
}

GET /posts/{post_id}

Retorna detalhes de um post específico.

PUT /posts/{post_id}

Atualiza um post do usuário.

Headers: Authorization: Bearer {token}

DELETE /posts/{post_id}

Exclui um post do usuário.

GET /posts/trending

Lista posts em tendência.

GET /posts/popular

Lista posts populares.

GET /users/{user_id}/posts

Lista posts de um usuário específico.

❤️ Interações

POST /posts/{post_id}/like

Curte um post.

Headers: Authorization: Bearer {token}

Response (200):

{
  "liked": true,
  "likes_count": 4501
}

DELETE /posts/{post_id}/like

Remove curtida de um post.

POST /posts/{post_id}/favorite

Adiciona post aos favoritos.

Response (200):

{
  "favorited": true,
  "favorites_count": 901
}

DELETE /posts/{post_id}/favorite

Remove post dos favoritos.

POST /posts/{post_id}/share

Compartilha um post.

Response (200):

{
  "shared": true,
  "shares_count": 1801,
  "share_url": "https://eleva.com/posts/post_abc123"
}

💬 Comentários

GET /posts/{post_id}/comments

Lista comentários de um post.

Query Parameters:

  • page (int): Página (padrão: 1)
  • limit (int): Limite por página (padrão: 20)
  • sort (string): Ordenação (recent, popular)

Response (200):

{
  "comments": [
    {
      "id": "comm_xyz789",
      "content": "Que frase inspiradora! Muito obrigada por compartilhar.",
      "author": {
        "id": "usr_67890",
        "name": "João Silva",
        "username": "joaosilva",
        "avatar_url": "https://cdn.eleva.com/avatars/usr_67890.jpg"
      },
      "likes": 45,
      "user_liked": false,
      "created_at": "2025-03-24T11:20:00Z",
      "replies_count": 3
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 95
  }
}

POST /posts/{post_id}/comments

Adiciona comentário a um post.

Headers: Authorization: Bearer {token}

Request Body:

{
  "content": "Muito inspirador! Obrigado por compartilhar."
}

PUT /comments/{comment_id}

Edita um comentário.

DELETE /comments/{comment_id}

Exclui um comentário.

POST /comments/{comment_id}/like

Curte um comentário.

GET /comments/{comment_id}/replies

Lista respostas de um comentário.

POST /comments/{comment_id}/replies

Responde a um comentário.

🏷️ Categorias

GET /categories

Lista todas as categorias disponíveis.

Response (200):

{
  "categories": [
    {
      "id": "cat_1",
      "name": "Motivação",
      "description": "Frases para motivar e inspirar",
      "color": "#FFD700",
      "icon": "lightbulb",
      "posts_count": 2450
    },
    {
      "id": "cat_2",
      "name": "Sucesso",
      "description": "Frases sobre conquistas e realizações",
      "color": "#FF6B6B",
      "icon": "trophy",
      "posts_count": 1890
    },
    {
      "id": "cat_3",
      "name": "Superação",
      "description": "Frases sobre resiliência e superação",
      "color": "#4ECDC4",
      "icon": "trending-up",
      "posts_count": 1650
    }
  ]
}

GET /categories/{category_id}/posts

Lista posts de uma categoria específica.

🔍 Busca

GET /search

Busca geral na plataforma.

Query Parameters:

  • q (string): Termo de busca (obrigatório)
  • type (string): Tipo de busca (posts, users, hashtags, all)
  • category (string): Filtrar por categoria
  • page (int): Página
  • limit (int): Limite por página

Response (200):

{
  "query": "motivação",
  "results": {
    "posts": [
      {
        "id": "post_abc123",
        "quote": "Cada dia é uma nova oportunidade...",
        "author": {
          "name": "Maria Santos",
          "username": "mariasantos"
        },
        "relevance_score": 0.95
      }
    ],
    "users": [
      {
        "id": "usr_12345",
        "name": "Maria Motivadora",
        "username": "mariamot",
        "follower_count": 1250
      }
    ],
    "hashtags": [
      {
        "name": "motivacao",
        "posts_count": 5200
      }
    ]
  },
  "total_results": 847
}

GET /search/suggestions

Retorna sugestões de busca.

Query Parameters:

  • q (string): Termo parcial

📊 Estatísticas e Rankings

GET /stats/trending

Retorna conteúdo em tendência.

Response (200):

{
  "trending_posts": [
    {
      "id": "post_abc123",
      "quote": "A persistência realiza o impossível.",
      "growth_rate": 0.85,
      "current_likes": 1200,
      "trend_duration": "2h"
    }
  ],
  "trending_hashtags": [
    {
      "name": "foco",
      "posts_count": 2400,
      "growth_rate": 0.45
    }
  ],
  "trending_users": [
    {
      "id": "usr_67890",
      "name": "João Inspirador",
      "new_followers": 150,
      "growth_rate": 0.35
    }
  ]
}

GET /stats/leaderboard

Ranking de usuários mais ativos.

Query Parameters:

  • period (string): Período (week, month, year, all-time)
  • metric (string): Métrica (likes, posts, followers)

GET /users/{user_id}/stats

Estatísticas detalhadas de um usuário.

📱 Feed Personalizado

GET /feed

Feed personalizado baseado nos usuários seguidos.

Headers: Authorization: Bearer {token}

Query Parameters:

  • page (int): Página
  • limit (int): Limite por página
  • algorithm (string): Algoritmo (chronological, recommended)

GET /feed/recommendations

Recomendações personalizadas para o usuário.

💾 Favoritos

GET /users/me/favorites

Lista posts favoritados pelo usuário.

Headers: Authorization: Bearer {token}

Response (200):

{
  "favorites": [
    {
      "id": "fav_123",
      "post": {
        "id": "post_abc123",
        "quote": "A vida é o que acontece enquanto você está ocupado...",
        "author": {
          "name": "John Lennon",
          "username": "johnlennon"
        }
      },
      "favorited_at": "2025-03-20T15:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 8,
    "total_items": 156
  }
}

🏷️ Hashtags

GET /hashtags

Lista hashtags populares.

Response (200):

{
  "hashtags": [
    {
      "name": "motivacao",
      "posts_count": 5200,
      "trending": true
    },
    {
      "name": "sucesso",
      "posts_count": 4700,
      "trending": true
    },
    {
      "name": "foco",
      "posts_count": 2400,
      "trending": false
    }
  ]
}

GET /hashtags/{hashtag}/posts

Posts que contêm uma hashtag específica.

🔔 Notificações

GET /notifications

Lista notificações do usuário.

Headers: Authorization: Bearer {token}

Response (200):

{
  "notifications": [
    {
      "id": "notif_123",
      "type": "like",
      "message": "João Silva curtiu seu post",
      "data": {
        "user_id": "usr_67890",
        "post_id": "post_abc123"
      },
      "read": false,
      "created_at": "2025-03-24T12:30:00Z"
    },
    {
      "id": "notif_124",
      "type": "follow",
      "message": "Ana Pereira começou a seguir você",
      "data": {
        "user_id": "usr_11111"
      },
      "read": true,
      "created_at": "2025-03-24T10:15:00Z"
    }
  ],
  "unread_count": 5
}

PUT /notifications/{notification_id}/read

Marca notificação como lida.

PUT /notifications/read-all

Marca todas as notificações como lidas.

📤 Upload de Mídia

POST /upload/image

Faz upload de uma imagem.

Headers:

  • Authorization: Bearer {token}
  • Content-Type: multipart/form-data

Request Body: FormData com campo image

Response (200):

{
  "url": "https://cdn.eleva.com/uploads/img_abc123.jpg",
  "thumbnail_url": "https://cdn.eleva.com/uploads/thumb_img_abc123.jpg",
  "file_size": 2048576,
  "dimensions": {
    "width": 1920,
    "height": 1080
  }
}

⚙️ Configurações

GET /users/me/settings

Retorna configurações do usuário.

Headers: Authorization: Bearer {token}

PUT /users/me/settings

Atualiza configurações do usuário.

Request Body:

{
  "privacy": "public",
  "notifications": {
    "likes": true,
    "comments": true,
    "follows": true,
    "email_digest": false
  },
  "content_preferences": {
    "mature_content": false,
    "preferred_categories": ["cat_1", "cat_3"]
  }
}

📊 Analytics (Para Criadores)

GET /users/me/analytics

Estatísticas detalhadas para criadores de conteúdo.

Headers: Authorization: Bearer {token}

Query Parameters:

  • period (string): Período (week, month, quarter, year)

Response (200):

{
  "overview": {
    "total_views": 15420,
    "total_likes": 3240,
    "total_comments": 890,
    "total_shares": 1150,
    "growth_rate": 0.15
  },
  "posts_performance": [
    {
      "post_id": "post_abc123",
      "views": 2450,
      "engagement_rate": 0.18,
      "best_performing_metric": "likes"
    }
  ],
  "audience_insights": {
    "top_countries": ["BR", "PT", "US"],
    "age_demographics": {
      "18-24": 0.25,
      "25-34": 0.35,
      "35-44": 0.30,
      "45+": 0.10
    }
  }
}

🚫 Moderação e Reportes

POST /posts/{post_id}/report

Reporta um post inadequado.

Headers: Authorization: Bearer {token}

Request Body:

{
  "reason": "spam",
  "description": "Conteúdo promocional repetitivo"
}

POST /users/{user_id}/block

Bloqueia um usuário.

GET /users/me/blocked

Lista usuários bloqueados.

🔄 WebSockets (Tempo Real)

Connection

wss://api.eleva.com/ws?token={jwt_token}

Eventos Enviados pelo Cliente

{
  "type": "subscribe_notifications",
  "user_id": "usr_12345"
}

Eventos Recebidos do Servidor

{
  "type": "new_notification",
  "data": {
    "id": "notif_125",
    "type": "like",
    "message": "Alguém curtiu seu post",
    "created_at": "2025-03-24T14:30:00Z"
  }
}

📋 Códigos de Status HTTP

Código Descrição
200 Sucesso
201 Criado com sucesso
400 Requisição inválida
401 Não autorizado
403 Proibido
404 Não encontrado
422 Entidade não processável
429 Muitas requisições
500 Erro interno do servidor

🔒 Rate Limiting

Endpoint Limite
Autenticação 5 req/min
Posts (GET) 100 req/min
Posts (POST) 10 req/min
Upload 20 req/min
Busca 50 req/min
Geral 1000 req/hour

🌐 Versionamento

A API usa versionamento semântico na URL:

  • v1 - Versão atual estável
  • v2 - Próxima versão (em desenvolvimento)

Mudanças que quebram compatibilidade requerem nova versão major.

💡 Exemplos de Integração

Curtir um Post

const likePost = async (postId, token) => {
  const response = await fetch(`https://api.eleva.com/v1/posts/${postId}/like`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });
  
  return response.json();
};

Buscar Posts por Categoria

const getPostsByCategory = async (categoryId, page = 1) => {
  const response = await fetch(
    `https://api.eleva.com/v1/posts?category=${categoryId}&page=${page}&limit=20`
  );
  
  return response.json();
};

Esta documentação cobre todas as funcionalidades principais identificadas no app Eleva, incluindo autenticação, gestão de usuários, posts, interações sociais, busca, notificações e muito mais. A API foi projetada seguindo padrões REST e boas práticas de desenvolvimento.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages