API CC

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 computacao.ch@uffs.edu.br

Utilização da API

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/ping

Para 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

Endpoints

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.

Desenvolvimento

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.

1. Dependências

Para executar o projeto, você precisa ter o seguinte instalado:

• Git;
• PHP;
• Composer;
• MySQL;
• NodeJS;
• NPM;

Você precisa de várias extensões PHP instaladas também:

sudo apt install php-cli php-mbstring php-zip php-xml php-curl

2. Configuração

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.

2.1 PHP

Instale as dependências do PHP usando o comando abaixo:

composer install

2.2 Banco de Dados

O banco de dados mais simples para uso é o SQLite. Para criar uma base usando esse SGBD, rode:

touch database/database.sqlite

2.3 Node

Instale também as dependências do NodeJS executando:

npm install

2.4 Laravel

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

2.5 Rodando o projeto

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.

Contribua

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.

Licença

Esse projeto é licenciado nos termos da licença open-source Apache 2.0 e está disponível de graça.

Changelog

Veja todas as alterações desse projeto no arquivo CHANGELOG.md.

Projetos semelhates

Abaixo está uma lista de links interessantes e projetos similares:

• auth-iduffs
• Brasil.io
• Dados Abertos da UFFS