Esse repositório contém a aplicação que serve a API do curso disponível em api.uffs.cc. Ela é uma API REST que disponibiliza diversas funcionalidades e dados que podem ser utilizados por serviços digitais curso, como aplicativos. Para utilizar a API, você precisa de uma chave de acesso (api key).
IMPORTANTE: Para conseguir uma chave de acesso, escreva para [email protected]
A API possui diversos endpoints disponíveis, todos acessíveis através de um prefixo de versão. Por exemplo, para acessar o endpoint teste na versão v1 da API, a URL é:
https://api.uffs.cc/v0/teste
A versão estável da API estará disponível no prefixo v1, enquanto a versão experimental (que pode mudar a qualquer momento), está disponível no prefixo v0.
Com exceção do enpoint auth, todos os endpoints precisam de uma chave de autenticação enviada através do seguinte cabeçalho HTTP:
Authorization: Bearer XXX
onde XXX é o valor da sua chave de acesso, por exemplo c08cbbfd6eefc83ac6d23c4c791277e4.
Abaixo está um exemplo de requisição para o endpoint v0/ping utilizando a chave de acesso acima:
curl -H 'Accept: application/json' -H "Authorization: Bearer c08cbbfd6eefc83ac6d23c4c791277e4" https://api.uffs.cc/v0/pingPara os endpoints que não necessitam do token, basta enviar os parâmetros:
curl -H 'Accept: application/json' -d "user=meuiduffsaqui&password=minhasenhaaqui" http://api.uffs.cc/v0/auth| Verbo | URL | Parâmetros | Retorno | Informação |
|---|---|---|---|---|
POST |
/auth | user (string, idUFFS do usuário)password (string) |
token (string JWT)passport (string JWT)user (objeto) |
Autentica um usuário utilizando o idUFFS (e sua senha). Não exige token. O campo token do retorno deve ser salvo e utilizado para chamadas subsequentes aos endpoints através do Authorization: Bearer XXX, onde XXX é o valor de token. O campo passport do retorno deve ser salvo e utilizado como parâmetro em todas chamadas subsequentes a endpoints que retornem dados pessoais ou façam qualquer alteração, ex. histórico escolar. |
As seções seguintes apresentam instruções para você baixar e rodar a aplicação localmente na sua máquina. Isso é útil se você estiver desenvolvendo algo. Se você deseja apenas utilizar a API, veja a seção anterior.
Para executar o projeto, você precisa ter o seguinte instalado:
Você precisa de várias extensões PHP instaladas também:
sudo apt install php-cli php-mbstring php-zip php-xml php-curl
Feito a instalação das dependências, é necessário obter uma cópia do projeto. A forma recomendada é clonar o repositório para a sua máquina.
Para isso, rode:
git clone --recurse-submodules https://github.com/ccuffs/api.uffs.cc && cd api.uffs.cc
Isso criará e trocará para a pasta api.uffs.cc com o código do projeto.
Instale as dependências do PHP usando o comando abaixo:
composer install
O banco de dados mais simples para uso é o SQLite. Para criar uma base usando esse SGBD, rode:
touch database/database.sqlite
Instale também as dependências do NodeJS executando:
npm install
Crie o arquivo .env a partir do arquivo .env.example gerado automaticamente pelo Laravel:
cp .env.example .env
Após isso, no arquivo .env altere o valor do campo DB_CONNECTION para sqlite. Também altere o valor de DB_DATABASE para o caminho do seu arquivo database.sqlite criado anteriormente, por exemplo /mnt/d/www/api.uffs.cc/database/database.sqlite.
No final, parte do seu arquivo .env ficará assim:
DB_CONNECTION=sqlite
DB_DATABASE=D:/wamp/www/api-cc/database/database.sqlite
Feita as alterações no .env execute o seguinte comando para a criação dos esquemas:
php artisan migrate
Por fim execute o comando abaixo para a geração da chave de autenticação da aplicação:
php artisan key:generate
Finalmente, após seguido os passos anteriores, gere os recursos JavaScript e CSS:
npm run dev
e por fim inicie o servidor do Laravel:
php artisan serve
Após isso a aplicação estará rodando na porta 8000 e poderá ser acessada em localhost:8000.
Sua ajuda é muito bem-vinda, independente da forma! Confira o arquivo CONTRIBUTING.md para conhecer todas as formas de contribuir com o projeto. Por exemplo, sugerir uma nova funcionalidade, reportar um problema/bug, enviar um pull request, ou simplemente utilizar o projeto e comentar sua experiência.
Veja o arquivo ROADMAP.md para ter uma ideia de como o projeto deve evoluir.
Esse projeto é licenciado nos termos da licença open-source Apache 2.0 e está disponível de graça.
Veja todas as alterações desse projeto no arquivo CHANGELOG.md.
Abaixo está uma lista de links interessantes e projetos similares: