O documento aborda práticas recomendadas para a construção de APIs, enfatizando a importância da documentação, como Swagger/Open API, para a acessibilidade e clareza. Destaca também a diferenciação entre Laravel e Lumen, além de fornecer diretrizes sobre versionamento, autenticação e segurança das APIs. O apresentador, Ravan Scafi, sugere utilizar boas práticas de design, formato de resposta e segurança para criar APIs eficazes e manuteníveis.

1. APIS DO JEITO CERTO
RAVAN SCAFI

2. • Ravan Scafi
• Web Developer @ Leroy
Merlin
• Co-organizador do Meetup
do Laravel-SP
• twitter.com/ravanscafi
SOBRE MIM

3. SOBRE A APRESENTAÇÃO
• Motivação
• Boas práticas na construção de APIs
• Lições Aprendidas
• Laravel / Lumen ao resgate!

4. APIS REST EM 1 MINUTO
• Recursos como substantivos
• Verbos HTTP especificam a ação
$ curl -XGET localhost/api/users/123

5. MOTIVAÇÃO
• Por que escrever uma API?
• O que implica ter uma API?

6. # DOCUMENTAÇÃO

7. “Uma API é apenas tão boa quanto
sua documentação”
apiary.io

9. SWAGGER / OPEN API
• Uma forma de documentar sua API
• Único arquivo swagger.json
• Consumível por Humanos e por Máquinas
• Swagger-UI: ❤️ ❤️ ❤️ ❤️

11. DOCUMENTAÇÃO: DICAS
• Mantenha a documentação próxima ao código
• Regras de bom código também valem para
documentação
• https://github.com/zircote/swagger-php

12. <?php
class UserController
{
/**
* @SWGPost(path="/user",
* tags={"user"},
* summary="Create user",
* description="This can only be done by the logged in user.",
* operationId="createUser",
* produces={"application/xml", "application/json"},
* @SWGParameter(
* in="body",
* name="body",
* description="Created user object",
* required=false,
* @SWGSchema(ref="#/definitions/User")
* ),
* @SWGResponse(response="default", description="successful operation")
* )
*/
public function createUser()
{
}
}
Swagger-PHP: Exemplo

13. <?php
$basePath = __DIR__ . '/..';
require_once $basePath . '/vendor/autoload.php';
// grabbing info from .env file
$beforeEnv = $_ENV;
(new DotenvDotenv($basePath))->load();
$envVars = array_diff($_ENV, $beforeEnv);
// grabbing info from composer.json file
$composerFile = json_decode(file_get_contents($basePath . '/composer.json'));
$composerInfo = [
'COMPOSER_NAME' => $composerFile->name ?? null,
'COMPOSER_DESCRIPTION' => $composerFile->description ?? null,
'COMPOSER_VERSION' => $composerFile->version ?? '0.0.0',
'COMPOSER_LICENSE' => $composerFile->license ?? null,
];
// defining grabbed info as constants
$desiredConstants = array_filter(array_merge($envVars, $composerInfo));
array_map('define', array_keys($desiredConstants), $desiredConstants);
bootstrap/swagger.php

14. {
...
"autoload": {
"psr-4": {
"App": "app/"
}
},
"scripts": {
"api-docs": "swagger app -o public/docs.json -b bootstrap/swagger.php",
}
}
composer.json
$ composer api-docs

15. # DESIGN

16. VERSIONAMENTO
• Internamente: Semantic Versioning
• Publicamente: só mude versões cheias (v1, v2)
• Evite Breaking Changes (BC) o máximo que
conseguir

17. O QUE CONFIGURA UMA BC?
• Remover campos: SIM
• Renomear campos: SIM
• Adicionar campos: NÃO
• Adicionar recursos / endpoints: NÃO

18. PROTEJA-SE COM MUTATORS
• Apresentação e transformação dos dados
• Uma “barreira” entre os recursos e a API
• Typecasting, relacionamentos

19. <?php
use AcmeModelBook;
use LeagueFractal;
$books = Book::all();
$resource = new FractalResourceCollection($books, function(Book $book) {
return [
'id' => (int) $book->id,
'title' => $book->title,
'year' => $book->yr,
'author' => [
'name' => $book->author_name,
'email' => $book->author_email,
],
'links' => [
[
'rel' => 'self',
'uri' => '/books/'.$book->id,
]
]
];
});
Transformer: Exemplo

20. NEGOCIAÇÃO DE CONTEÚDO
• JSON é JavaScript, portanto use camelCase
• /api/user/123.json, /api/user/123.csv
• Recursos embedados: trazer dinamicamente ou não
• Metadados: URI, página atual, count total
• Verbo HTTP: override com _method

21. RESPOSTAS
• Padronize campos como: datas, floats, moedas
• Padronize códigos HTTP de resposta
• Padronize paginação, metadados, etc.

22. RESPOSTAS
• Faça um “wrap” da resposta em uma chave “data”
• Mostre o erro, ao invés de um código de erro
• Nunca exponha exceptions para os usuários
• Não reinvente a roda, seja coerente com padrões

23. AUTENTICAÇÃO
• Baseados em Sessão: NÃO
• APIs devem ser sem estados (stateless)
• Implementação em mobile é custosa
• Baseados em Token: SIM
• OAuth? OAuth2? JWT? Http-Basic?

24. OAUTH VS JWT
• Não são “concorrentes” diretos
• É até mesmo possível utilizar os dois em conjunto
• OAuth: concebido para autorização (pseudo
autenticação)
• 3-legged vs 2-legged
• JWT: concebido para claims / autenticação

25. Como se parece um token JWT

26. SEGURANÇA
• Evite expor IDs sequenciais
• Limite as requisições (Throttling), porém configurável
por conta
• Não utilize sessões ou logins por senhas (exceto em
aplicativos próprios)
• API somente em HTTPS
• Verifique sempre vulnerabilidades com OAuth / JWT

27. # LARAVEL VS LUMEN

28. LARAVEL VS LUMEN
• Já tenho um app em Laravel: Laravel!
• Já tenho um app em Lumen: Lumen!
• Vou começar: Lumen!
• Use e abuse de Middlewares
• Agrupe rotas por versão

29. <?php
$app->group(['prefix' => 'api'], function () use ($app) {
$app->group(['prefix' => 'v1'], function () use ($app) {
$app->get('users', function () {});
$app->get('products', function () {});
});
$app->group(['prefix' => 'v2'], function () use ($app) {
$app->get('users', function () {});
$app->get('products', function () {});
});
});
Grupos de Rotas por Versão

30. PACOTES ÚTEIS
• Dingo/API
• Zircote/Swagger-PHP
• TymonDesigns/JWT-Auth
• League - OAuth2 Server
• League - Fractal
• Ramsey - UUID

31. DINGO/API
• Negociação de Conteúdo
• Múltiplos Adaptadores de Autenticação
• Versionamento da API
• Limitação de Requisições

32. DINGO/API
• Transformers and Formatters de Respostas
• Handling de Exceptions e Erros
• Requests Internos
• Documentação Blueprint

33. • Build APIs You Won't Hate
• Heroku's HTTP API
Design
• Open API Initiative
• Petstore (demo swagger)
• 2-legged OAuth
LIVROS E RECURSOS

34. LEMBREM-SE: EMPATIA É A CHAVE

35. OBRIGADO!
@ravanscafi

36. ESTAMOS CONTRATANDO :)
rscafi@leroymerlin.com.br