# API: Overview

---

- [Introdução](#introducao)
- [Padrões de endpoints](#padroes_endpoints)
- [Resource Controller Base](#resource_controller)
- [Códigos de Resposta Comuns](#codigos_de_resposta_comuns)

<a name="introducao"></a>
## Introdução

Esta é a documentação da API RESTful utilizada na nossa aplicação. A API segue as convenções padrão REST e adota os padrões comuns usados no Laravel para facilitar o desenvolvimento e a integração com outros sistemas.

<a name="padroes_endpoints"></a>
## Padrões RESTful

Os endpoints devem seguir o padrão da framework, ou seja, devem seguir convenções RESTful para organizar e simplificar a definição de rotas. Aqui está uma visão geral dos principais padrões:

### Nomenclatura Endpoints

O nome dos endpoints sempre devem ser pluralizados, então se desejo criar manipulações da entidade **pessoa** eu devo criar os endpoints pluralizados para **pessoas**. Isso é um padrão que torna os endpoints mais intuitivos e semânticos.

O principal motivo das coleções de recursos (como uma lista de registros) deverem ser representadas de forma plural, é para refletir o fato de que o endpoint pode manipular múltiplos objetos do mesmo tipo.

Por exemplo:

 - GET /users – Retorna uma lista de usuários, ou seja, uma coleção de recursos, logo, o plural faz sentido.
 - POST /users – Cria um novo usuário, novamente indicando que estamos trabalhando com uma coleção de usuários.

Em contraste, quando se trata de um único item:

 - GET /users/{id} – Retorna informações de um único usuário, em que o identificador específico é utilizado para acessar esse recurso individual.

Essa convenção ajuda a melhorar a clareza e a consistência da estrutura da API, facilitando a compreensão de como os endpoints devem ser usados, especialmente quando se trabalha com APIs RESTful.

### Resources

Laravel permite a criação de rotas RESTful com o método Route::resourceApi, que gera endpoints para operações CRUD (Create, Read, Update, Delete).

```php
Route::resourceApi('pessoas', PessoaController::class);
```

Isso gera os seguintes endpoints:

| # | Método | Rota |
| : |   :-     |  : |
| 1 | GET   | pessoas  |
| 2 | GET   | pessoas/{pessoa} |
| 3 | POST | pessoas |
| 4 | PUT | pessoas/{pessoa} |
| 5 | DELETE | pessoas/{pessoa} |

### Criando somente rotas necessárias

Não devemos criar nenhuma rota "morta", ou seja, sem de fato uma implementação de funcionalidade correspondente.

Para isso, selecionando com método **only()** somente o que necessitamos do resource:

```php
Route::resourceApi('pessoas', PessoaController::class)->only(['index', 'show', 'update']);
```

Isso gera os seguintes endpoints:

| # | Método | Rota |
| : |   :-     |  : |
| 1 | GET   | pessoas  |
| 2 | GET   | pessoas/{pessoa} |
| 4 | PUT | pessoas/{pessoa} |

<a name="resource_controller"></a>
## Resource Controller Base

A classe ```App\Http\Controllers\ResourceApiController``` foi desenvolvida para promover facilidade e agilidade na criação de controllers para operações comuns na API. Este controlador base encapsula comportamentos e operações padrão, permitindo que outros controllers estendam sua funcionalidade e personalizem apenas o necessário.

### Objetivo

O objetivo principal é reduzir a repetição de código em operações como:

 - Listagem de registros (index, indexByCompany);
 - Exibição de um registro específico (show);
 - Criação de registros (store, storeByCompany);
 - Atualização de registros (update, updateByCompany);
 - Exclusão de registros (destroy).

<a name="codigos_de_resposta_comuns"></a>
## Códigos de resposta Comuns

A API retorna códigos de status HTTP padrão para indicar o resultado de cada requisição:

- **200 OK**: Requisição bem-sucedida.
- **201 Created**: Recurso criado com sucesso.
- **400 Bad Request**: Erro na requisição (dados inválidos).
- **401 Unauthorized**: Falta de autenticação ou autorização.
- **404 Not Found**: Recurso não encontrado.
- **422 Unprocessable Entity**: Erro de validação em requisição à endpoint.
- **500 Internal Server Error**: Erro inesperado no servidor.