Game Ranking API

Microsserviço backend responsável por disponibilizar rankings e métricas de jogos para integração com o ecossistema GameVerse.

---

Sobre o Projeto

Este serviço centraliza dados de engajamento de jogos e disponibiliza endpoints JSON para que um site, frontend ou outro microsserviço consiga exibir rankings dinâmicos.

O projeto contém apenas o backend da API. A interface visual do usuário final fica em outro projeto consumidor.

---

Integrantes

• Kaiky Andrade de Oliveira
• Gabriel Henrique Lina Batista Pereira Nunes

---

Responsabilidades do Microsserviço

• Fornecer ranking semanal, mensal e anual de jogos
• Listar os jogos mais jogados
• Consultar histórico de pontuação de um jogo
• Filtrar rankings por plataforma
• Retornar dados estatísticos em formato JSON
• Proteger as rotas da API usando JWT
• Disponibilizar documentação interativa com Scribe

---

Tecnologias Utilizadas

• PHP >= 8.1
• Laravel 10
• SQLite
• Composer
• Laravel Scribe
• PHPUnit

---

Estrutura do Repositório

Este repositório não está organizado como monorepo. Ele contém apenas o microsserviço backend da API de rankings de jogos.

Serviço	Pasta	Descrição
API de Rankings de Jogos	/	Backend Laravel responsável pelas rotas, autenticação JWT, rankings e documentação Scribe

Principais pastas:

Pasta	Finalidade
app/Http/Controllers	Controllers da API
app/Http/Middleware	Middleware de autenticação JWT
app/Models	Models Eloquent
routes/api.php	Rotas da API
routes/web.php	Rotas web básicas
database/migrations	Estrutura das tabelas
database/seeders	Dados iniciais para demonstração
resources/views/scribe	Documentação HTML gerada pelo Scribe
public/vendor/scribe	Assets públicos da documentação
tests/Feature	Testes dos endpoints e da documentação

---

Requisitos

Antes de executar o projeto, instale:

• PHP >= 8.1
• Composer
• Git
• SQLite

---

Instalação

Clone o repositório:

git clone https://github.com/gabriellina640/api-ranking-jogos.git
cd api-ranking-jogos

Instale as dependências:

composer install

Crie o arquivo .env:

cp .env.example .env

Gere a chave da aplicação:

php artisan key:generate

Crie o banco SQLite local:

touch database/database.sqlite

No .env, configure:

DB_CONNECTION=sqlite

Execute as migrations e seeders:

php artisan migrate:fresh --seed

---

Variáveis de Ambiente

Principais variáveis usadas pelo projeto:

Variável	Descrição
APP_NAME	Nome da aplicação
APP_ENV	Ambiente da aplicação
APP_KEY	Chave interna do Laravel
APP_DEBUG	Ativa ou desativa debug
APP_URL	URL base da aplicação
DB_CONNECTION	Driver do banco, atualmente sqlite
JWT_ISSUER	Emissor esperado no token JWT
JWT_AUDIENCE	Audiência esperada no token JWT
JWT_PUBLIC_KEY_PEM	Chave pública usada para validar JWT RS256
SCRIBE_AUTH_KEY	Token usado apenas para gerar exemplos 200 na documentação

---

Autenticação

As rotas da API usam autenticação via JWT no padrão Bearer Token.

Todas as requisições para os endpoints /api/v1/* devem enviar:

Authorization: Bearer SEU_TOKEN_JWT
Accept: application/json

O token precisa:

• usar algoritmo RS256
• ter iss igual ao valor de JWT_ISSUER
• ter aud igual ao valor de JWT_AUDIENCE
• ter sub preenchido
• ter exp válido
• ter assinatura compatível com JWT_PUBLIC_KEY_PEM

Sem o header Authorization, a API retorna 401.

---

Executando o Projeto

Inicie o servidor Laravel:

php artisan serve

A aplicação ficará disponível em:

http://localhost:8000

---

Documentação da API

Gere a documentação:

php artisan scribe:generate

Acesse:

http://localhost:8000/docs

Links auxiliares:

Recurso	URL
Documentação interativa	http://localhost:8000/docs
Collection Postman	http://localhost:8000/docs.postman
OpenAPI	http://localhost:8000/docs.openapi

---

Rotas da API

Método	Endpoint	Descrição	Autenticação
GET	/api/v1/rankings/weekly	Lista o top 10 jogos por pontuação semanal	JWT
GET	/api/v1/rankings/monthly	Lista o top 10 jogos por pontuação mensal	JWT
GET	/api/v1/rankings/yearly	Lista o top 10 jogos por pontuação anual	JWT
GET	/api/v1/rankings/history/{id}	Retorna o histórico de pontuação de um jogo	JWT
GET	/api/v1/rankings/platforms/{platform}	Lista jogos filtrados por plataforma	JWT
GET	/api/v1/games/most-played	Lista o top 10 jogos por jogadores ativos	JWT

Existe também a rota técnica GET /api/test-auth, usada apenas para validar o token JWT. Ela não faz parte da documentação pública principal.

---

Exemplos de Requisição

Ranking semanal:

GET /api/v1/rankings/weekly HTTP/1.1
Host: localhost:8000
Accept: application/json
Authorization: Bearer SEU_TOKEN_JWT

Ranking por plataforma:

GET /api/v1/rankings/platforms/Steam HTTP/1.1
Host: localhost:8000
Accept: application/json
Authorization: Bearer SEU_TOKEN_JWT

Histórico de um jogo:

GET /api/v1/rankings/history/1 HTTP/1.1
Host: localhost:8000
Accept: application/json
Authorization: Bearer SEU_TOKEN_JWT

---

Exemplo de Resposta

[
  {
    "id": 1,
    "name": "Counter-Strike 2",
    "platform": "Steam",
    "active_players": 1086549,
    "weekly_points": 729,
    "monthly_points": 1215,
    "yearly_points": 71182,
    "created_at": "2026-05-18T21:57:31.000000Z",
    "updated_at": "2026-05-18T21:57:31.000000Z"
  }
]

---

Retornos Esperados

Código	Situação	Exemplo
200	Requisição autenticada com sucesso	Lista de jogos ou histórico
401	Token ausente, inválido ou expirado	{"message":"Missing Authorization header"}
404	Jogo inexistente em /rankings/history/{id}	Resposta padrão do Laravel para model não encontrado
500	Erro inesperado no servidor	Falha interna

Observação: quando uma plataforma não possui jogos, /api/v1/rankings/platforms/{platform} retorna 200 com lista vazia.

---

Testes

Execute:

php artisan test

Os testes cobrem:

• exigência de autenticação JWT
• ranking semanal, mensal e anual
• jogos mais jogados
• histórico por jogo
• filtro por plataforma
• rota técnica de teste de autenticação
• correspondência entre OpenAPI/Scribe e rotas públicas da API

---

Integração com o Projeto Consumidor

O site ou microsserviço consumidor deve:

1. obter um JWT válido no serviço de autenticação do ecossistema;
2. enviar o token no header Authorization;
3. consumir os endpoints /api/v1/*;
4. tratar respostas 401 quando o token estiver ausente, inválido ou expirado.

Este microsserviço atualmente não emite tokens. Ele apenas valida tokens JWT RS256.

---

Dados do Serviço

Atualmente os dados são armazenados na tabela games e podem ser populados pelos seeders do Laravel.

Campos principais:

Campo	Descrição
name	Nome do jogo
platform	Plataforma do jogo
active_players	Quantidade de jogadores ativos
weekly_points	Pontuação semanal
monthly_points	Pontuação mensal
yearly_points	Pontuação anual

---

Fluxo Principal

1. O consumidor solicita um ranking.
2. A API valida o JWT.
3. O controller consulta a tabela games.
4. Os dados são ordenados conforme o endpoint.
5. A resposta JSON é retornada ao consumidor.

---

Arquivos da Entrega

Este repositório contém:

• README.md
• .env.example
• código-fonte Laravel
• migrations
• seeders
• testes
• documentação Scribe gerada

A pasta vendor/ não deve ser enviada para o GitHub.

---

Contato

Projeto acadêmico desenvolvido para a disciplina de Microsserviços no contexto do ecossistema GameVerse.