API Design

Reference Guide
 Por que
investir em uma
estratégia de API
A A disrupção digital tem impactado profundamente todas as empresas. A rapidez das trans-
formações evoluí a um ritmo nunca visto na história. A necessidade é iminente para ser ágil e
inovador.

A economia das APIs tem sido uma pedra fundamental dessa história. O crescimento de novas
conexões e trocas de valores entre empresas, dispositivos e sistemas é exponencial. Empresas
tem adotado APIs não apenas para endereçar questões técnicas, mas também para criar novos
modelos de negócio. Abaixo os principais cenários de uso:

> Experiência Digitais > Open Innovation & Platforms

As APIs aceleram a criação de aplicações, APIs promovem inovação aberta criando o
permitindo a habilitação de estratégias Mo- ambiente ideal para Hackathons, experimen-
bile, Omnichannel e IoT. APIs destravam os tação e criação de novos modelos de negó-
legados criando uma camada ágil cios, aproximando a Startups e Ecossistemas
de Inovação.

> Ecossistemas de Parceiros > Arquitetura Ágil

APIs permitem integrações escaláveis, APIs são perfeitas como modelo para inte-
rápidas e com padrões globais de segu- grações internas entre sistemas. Fornece
rança para trocas de valores/informa- simplicidade, segurança, monitoramento e
ções entre empresas. governança. Habilita a criação de um modelo
híbrido de sistemas hospedados na cloud e
on-premise.

ESCLARECIMENTOS

Este guia de referência não reivindica ser absolutamente completo. Os conceitos de design des-
critos são resultados dos dilemas mais comuns no design de API. Acesse sensedia.com/resour-
ces e sinta-se à vontade para baixar este arquivo e comentar sobre o conteúdo deste encarte.
RESTful API
Design
A
Assim que começamos a trabalhar com APIs, normalmente surgem dúvidas e consequentes di-
lemas de Design. Um Design robusto é um fator-chave para o sucesso nas suas exposições. APIs
mal projetadas comumente levam a usos indevidos ou, pior ainda, acabam por não serem utiliza-
das pelos seus principais clientes: os desenvolvedores.

Para criação de uma API, e consequente exposição, é importante considerar:

• Utilização dos princípios RESTful, conforme descritos pelos seus principais idealizadores
(Roy Fielding, Leonard Richardson, Martin Fowler),
• As especificações HTTP, em detalhe
• Como opção, o acompanhamento sobre a forma com que os “Web Giants” utilizam APIs

Atualmente vemos duas abordagens opostas de implementação:

• Purista,
Purista que foca em seguir os princípios do REST independente de contexto.
• Pragmática,
Pragmática que trabalha uma abordagem mais personalizada, para fornecer aos seus
parceiros uma API mais prática no dia-a-dia.

→ A solução mais recomendada é permear entre as duas abordagens e criar a sua própria, ade-
quada ao seu contexto de desenvolvimento.

Projetar uma API REST levanta questões e problemas para os quais não há uma resposta univer-
sal. As melhores práticas REST ainda estão em debate, e sua consolidação ainda está em pro-
gresso.
Para facilitar - e acelerar - o design e o desenvolvimento das suas APIs, a SENSEDIA está com-
partilhando suas visões e recomendações neste encarte de referência. Este conteúdo vêm da
nossa expertise e vanguarda em atuação com APIs há mais de 10 anos.
Conceitos Gerais

K.I.S.S.
<Keep It Simple, Stupid/>
Q
Qualquer pessoa conseguirá utilizar a sua API sem a necessidade de consultar a documentação.

> Use termos padrões, concretos e públicos, e não utilize termos internos, comerciais ou
siglas específicas.
> Não permita que os desenvolvedores façam a mesma coisa de diversas formas
(padronize e reaproveite).
> Crie sua API para seus desenvolvedores, não para seus dados/sistemas.
> Priorize as APIs do seu negócio e depois disponibilize as exceções

NETWORK FALLACIES

> A rede é confiável > Não há latência

> Largura de banda é infinita > A rede é segura
> Topologia não muda > Há um administrador
> O custo do transporte é zero > A rede é homogênea

Exemplos Funcionais
Compartilhe cURL com exemplos simples e objetivos, copy/past funcionais.

CURL -X POST \
-H ‘Authorization: Basic ZWM3NDIxMQ==’ \
-H ‘Content-Type: application/x-www-form-urlencoded’ \
-d grant_type=client_credentials \
https://api.sensedia.com/oauth/access-token
 Granularidade
Recursos com granularidade “média”

Não seja muito detalhista ou pouco detalhista. Uma sugestão é a hierarquia dos recursos
não terem mais do que dois níveis de profundidade:

[GET] /clients/dr241s
{ “id”:”rt874f”,
“name”:”Fabrício Alves”,
“age”:”40”,
“address”:{
“street”:”Rua Dr. Zero”,
”city”:{“name”:”Campinas”}
}
}

Segurança
OAuth2/OIDC & HTTPS

Utilizar o OAuth2 para gerenciamento de Autenticações e Autorizações.

Esta técnica corresponde a 99% das requisições utilizadas. Não reinvente o que já funciona
muito bem.
Utilize sempre HTTPS (ssl/tls) nas suas exposições de API / OAuth2.

Nomes dos Environments

Sempre que possível disponibilize no mínimo 4 ambientes:

- Produção: api.sensedia.com
- Sandbox: api-sandbox.sensedia.com
- Teste/qa.: api-test.sensedia.com (interno)
- Desenvolvimento: api-dev.sensedia.com (interno)
 Substantivos
Utilize sempre substantivos e não verbos (vs SOAP-RPC).

utilize [GET]/clients e não [GET] /getClients

Pluralidade
Nomenclaturas com substantivo no plural.

Os recursos representam um conjunto de entidades, seu nome deve ser sempre no plural.

> Recurso de coleção: /orders

> Recurso de instância: /orders/aJg39Ya

Permaneça consistente.

utilize [GET]/users/s28er e não [GET] /user/s28er

* Exceções devem ser analisadas caso a caso

Estrutura hierárquica
URL criada por uma estrutura hierárquica com agregações ou decomposições e ordenado
por relevância.

Ex: O carrinho de compras contém produtos.

[GET] /shoppings/s28er/orders/r43ed/products
 Consistência da nomeação (case)
Utilize spinal-case na sua URI e lowerCamelCase ou spinal-case nos atributos, parâmetros
e values da sua header e body e permaneça consistente na sua escolha.

[GET] /beers?id-user=s28er ou [GET] /beers/price-client?user=s28er

[POST] /beers {“idUser”:”s28er”} ou [POST] /beers {“id-User”:”s28er”}

Obs: Caso utilize “snake_case”, assegure que os seus clientes sejam compatíveis com esse padrão, pois
alguns compiladores e Webservices ignoram o caractere “underline”.

Versionamento
Implemente o controle de versão na URL e exponha apenas o seu major version.

[GET] /v1/clients

Mantenha no máximo 2 versões ativas e, para a versão mais antiga defina a sua data
de desligamento (coloque esta informação na header dos responses “X-Api-Deadline”
e “X-Api-Deadline-Information”).

Operações API (CRUD)

Utilize os verbos HTTP para as operações CRUD (Create/Read/Update/Delete)

Recursos Get Post Patch Put Delete

status code>> <200> <201> <200> <200> <204>
Erro Erro Erro
../beers Listagem Criação
<HTTP Status 405> <HTTP Status 405> <HTTP Status 405>

Detalhamento de Erro Atualização par- Atualização da Exclusão da beer

../beers/dr241s
uma beer <HTTP Status 405> cial da beer beer dr241s dr241s

Listagem dos
../beers/dr241s/ Cria novo item na Erro Erro Erro
items da beer
items order dr241 <HTTP Status 405> <HTTP Status 405> <HTTP Status 405>
dr241s
 Pesquisa, Filtros, Respostas
parciais e Ordenações
Utilize notações de pesquisa e filtros para limitar o retorno dos seus registros de forma
eficiente.

[GET]../v1/beers?status=paid (subconjunto)
[GET]../v1/beers?_fields=number,date,address(street) (otimização com respostas parciais)
[GET]../v1/beers?_sort=date (ordenação ascendente)
[GET]../v1/beers?_desc=date (ordenação descendente)
[GET]../v1/beers?name=*Sensedia* (like)
[GET]../v1/beers?items=_greaterThan(10) (restrição “>=”)
[GET]../v1/beers?items=_lessThan(10) (restrição “<=)
[GET]../v1/beers?items=_between(4,8) (restrição)
[GET]../v1/beers?date=YYYY-MM-DDThh:mm:ssTZD (date)
[GET]../v1/beers?items=[2,4,8] (vetor)
[GET]../v1/beers?_first (primeiro registro)
[GET]../v1/beers?_last (último registro)
[GET]../v1/beers?_count (total registros)

** Todas as condições listadas acima devem ser interpretadas e tratadas no backend.

 Paginação

Utilize paginação para otimizar a performance do seu front-end (website e mobile)

[GET]../v1/client/84/beers (especificação pk)

[GET]../v1/client/84/beers/2/items (especificação pk + item)
[GET]../v1/beers?_records=10 (limitação)
[GET]../v1/beers?_offset=50&_limit=25 (agrupamento)

Nos requests de agrupamento informar no header do response os atributos:

- content-range: Total de registros existentes

- accept-range: Quantidade máxima de registros disponíveis

* Se passar um valor, nos atributos “_records” e/ou “_limit”, maior que o especificado no “ac-
cept-range”, teremos o erro Status Code 412.

** Todas as condições listadas acima devem ser interpretadas e tratadas no backend.

 I18N
Use o padrão ISO 8601 para Data / Hora / Registro de Data e Hora:

• Data: “YYYY-MM-DD”, onde será assumida a hora 00:00:00 do mesmo time zone do servidor;
• Hora: Utilizar “hh-mm-ss”;
• TimeStamp: Utilizado YYYY-MM-DDThh:mm:ssTZD, respectivamente data, hora e Time Zone.

Adicione suporte para diferentes idiomas.

Ignore notações específicas como en-US, en-CA … utilize apenas “en”

Estrutura de Dados
A solicitação de dados deve sempre seguir os padrões RESTful.

O conteúdo trafegado pelo body deve conter o formato JSON

Content-Type : application/json
 Exceções perigosas, porém
excepcionalmente necessárias
Por definição do RESTFul, qualquer operação deve ser visto e manipulado como um recurso.
Na vida real, nem sempre é possível, especialmente quando temos que lidar com ações como
traduções, cálculos, conversões, serviços empresariais complexos ou serviços fortemente
integrados (legado).

Em casos excepcionalmentes raros, nas requisições POST, você pode utilizar um “verbo” no
final da URI.

[POST] /calculator/sum
-> Body: [1,2,3,5,8,13,21]
[POST] /convert?from=EUR&to=USD&amount=4

No entanto, antes de seguir esta exceção, tenha certeza que as notações RESTful não te atende.

Hateoas
Sempre que possível disponibilize hyperlinks no response das sua APIs, desta forma possibi-
litará a obtenção de mais informações.

Mas não se iluda, por ser uma técnica relativamente nova, poucos utilizarão os hyperlinks.
Explicite esta possibilidade na sua documentação.

Utilize a notação RFC 5988 link para implementar o HATEOAS:

GET /users/dr241s
-> 200 Ok
-> {“id”: “dr241s”, “firstname”: “Fabrício”, “...”: “...”,
“links”: [ {
“href”: “addresses/18”,
“rel”: “addresses”,
“type”: “GET” } ] }

* Todas as condições listadas acima devem ser interpretadas e tratadas no backend

 HTTP Status codes

Successful - 2xx

Status genérico de sucesso.

200 OK Normalmente utilizado nas respostas dos GETs ou atualizações do PUT/PATCH.

Indica a criação de um recurso.

201 Created
Normalmente utilizado para responder as requisições dos POSTs.

Indica que a requisição foi “aceita” para processamento.

202 Accepted
Normalmente utilizada em chamadas assíncronas.

Indica a execução com sucesso de uma operação que não retornará infor-
204 No Content mação. Normalmente utilizada como resposta dos DELETEs, PUTs e GETs
em coleções vazias.

206 Partial O retorno está incompleto.

Content Normalmente utilizado em recursos com paginação (GETs condicionais).

ANT PATTERN

company.galleries.editPhoto
 Client Error - 4xx
400 GET /beers?barley=true
Status genérico de erro para requisições que não 400 Bad Request
Bad Request atende o número mínimo de requisitos atendidos. { “message”: “Parâmetro ‘barley’ inválido” }

401 Não autorizado devido a falta de GET /beers/42e2a

Unauthorized token ou expiração do mesmo. 401 Unauthorized
{ “message”: “Você precisa estar autenticado” }

403 Sua credencial não tem privilégios suficientes para GET /beers/42e2a/Ingredients
Forbidden acessar o recurso que está solicitando. 403 Forbidden
{ “message”: “Você não tem permissões suficientes” }

422 Ocorreu algum erro de negócio com sua mensagem. PUT /beers/42e2b
Unprocessable Sintaticamente correto, semanticamente não. 422 Unprocessable Entity
Entity { “message”: “O campo Ingredients está inválido” }

A requisição que você está enviando excedeu o PUT /beers/42e2b

413 limite de tamanho do payload que o servidor é 413 Entity Too Large
Entity Too Large capaz de processar. { “message”: “O servidor não consegue lidar
com esse volume de dados” }

429 Você está fazendo mais requisições do que o GET /beers/42e2b

429 Too Many Requests
Too Many Requests serviço permite. {“message”: “Você atingiu o limite máximo de
requisições no período”}

Indica que o servidor não encontrou o recurso

de origem ou destino (técnico). Pode não ser um GET /beers/barley
404
estado permanente -- que seria indicado por 410 404 Not Found
Not Found (Gone). Também utilizado quando um ID de uma { “message”: “Ooops. A página está inativo ou
coleção não existe no backend (exceção de negócio). o link está quebrado.” }

415 Erro de ausência de content header. Facilmente PUT /beers/42e2b

Unsupported Media resolvido com os atributos Content-Type ou 415 Unsupported Media Type
Type Content-Encoding. { “message”: “Media type inválido” }

Server Error - 5xx

Na maioria das vezes a requisição está errada, mas o GET /beers?barley=true
500 Internal
servidor não soube tratar e devolver um erro de negó- 500 Internal Server Error
Server Error cio da classe 4xx, desta forma retorna este status. { “message”: “Ops… Alguma coisa deu errado.” }

GET /beers/42e2a
503 Service O servidor não consegue processar agora devido a
503 Service Unavailable
Unavailable alguma indisponibilidade momentânea. { “message”: “O servidor não consegue processar
agora. Tente mais tarde.” }

504 Gateway O servidor não consegue processar agora devido a GET /beers/42e2a
504 Gateway Timeout
Timeout alguma sobrecarga momentânea.
{ “message”: “O servidor não consegue processar
agora. Tente mais tarde.” }

GET /beers/42e2a
502 Bad Gateway
502 Bad O Proxy Server ou API Gateway não conseguiu identi- { “message”: “The server, while acting as a gateway
Gateway ficar exatamente o “erro” reportado pelo Backend. or proxy, received an invalid response from an
inbound server it accessed while attempting to
fulfill the request.” }
 GraphQL

GraphQL - Fazendo um pouco

mais que o RESTful permite

GraphQL é uma Query Language baseada em grafos onde é possível consultar os nós e tam-
bém conexões entre eles.

Uma das principais limitações encontradas com REST e resolvidos pelo GraphQL é fornecer
exatamente o que o desenvolvedor precisa. Nada a mais e nada a menos. Isso inclui navegar
relacionamentos com outros nós (objetos) em uma única consulta, otimizando imensamen-
te o tráfego de informações ao desenvolvedor e evitando que novos endpoints específicos
sejam criados para otimizar um parceiro em particular.

Mas quando deve-se usar o Graphql? Lembre-se que não existe uma bala de prata, se uma
solução deu certo para um parceiro, não quer dizer que dará para você. Preparamos um che-
cklist para você decidir se deve ou não utilizar o Graphql, a Sensedia tem um time de consul-
tores que pode auxiliá-lo nesta decisão.
 GraphQL
Devo ou não utilizar?

Usar:
• Quando pode ser introduzido incrementalmente.

• Quando os aplicativos Mobile são os principais clientes.

• Você possui vários clientes que necessitam de informações diferentes (relacionadas) em

uma mesma chamada.

• Deseja apartar front-end e back-end para acelerar desenvolvimento.

• Estão puxando dados de uma variedade de fontes, como vários bancos de dados e estão
usando APIs externas que compõem uma única solução final.

• Se possui muitos recursos que são relacionados entre si.

Não Usar:
• Precisa ter um bom efeito com uma rede de desenvolvedores terceiros em prazo imediato.

• Estão profundamente integrados em ferramentas de ciclo de vida de API automatizadas

• Tenha um modelo de dados muito simples.

• Precisa aplicar cache na sua aplicação para não sobrecarregar o servidor.

Acesse para baixar este
material e tirar dúvidas.

sensedia.com/resources

19 3705.5775