dx_rest.md

DX (Developer Experience) - REST

Desafio

Construir APIs utilizando as boas práticas de mercado, tendo boas documentações que sirvam como SAAS, fazendo a API ser autoexplicativa e bem documentada sem a necessidade de iteração com a equipe criadora para o entendimento e/ou consumo.

Target

O time constrói e faz melhorias nas suas API REST, visando as boas práticas de mercado, níveis de maturidade REST e recomendações da Softplan? Levando em consideração o que se vê por fora (contratos API) para facilitar o consumo e a reutilização das mesmas.

• Niveis de maturidade REST
• Recomendações e boas praticas Softplan

Faixas

Evidências: Para esse tópico é necessário as URLs das APIs no padrão OPEN/API, para avaliação e histórico de evidência.

Branca

• Contexto de um repositório e uma API (de um sistema que possua API REST)
  • Há alguma API que trabalhe com conceito de serviço e não componente que seja totalmente independente de tecnologia específica para sua comunicação (comunicação via HTTP) ?
  • O time documenta a API com padrão OPEN/API
  • Há alguma API direcionada ao negócio e não ao frontend, uma integração específica, tecnologia ou banco dados?

Amarela

• Contexto de um repositório e todas as APIs desse repositório (de um sistema que possua API REST)
  • O time possui alguma API documentada no padrão OPEN/API publicada em algum lugar público ou com acesso fácil interno na empresa ?
    • Essa API é direcionada ao negócio (não ao frontend, uma integração específica, tecnologia ou banco dados) ?
    • Essa API publicada e documentada atende ao nível de maturidade REST: Level 1 - Resources ?
    • Essa API publicada e documentada atende ao nível de maturidade REST: Level 2 - HTTP Verbs ?
    • No contexto de boas práticas levando em consideração o ebook backend - a API está de acordo com:
      • “Utilize os nomes de recurso no plural, seja instância ou coleção”
      • “Utilize verbos/métodos HTTP para identificar as operações sobre os recursos, conforme a tabela a seguir”
      • “Utilize o formato de objeto JSON para estruturar qualquer dado/Use JSON to Encode Structured Data”
      • “Utilize underscore (_) para separar palavras em parâmetros/Use snake_case (never camelCase) for Query Parameters”
      • “Utilize underscore (_) para separar palavras em nomes de campo/Property names must be ASCII snake_case (and never camelCase)”

Laranja

• Contexto 51% dos repositório e todas as APIs desses repositórios (dos sistemas que possuem API REST)
  • O time possui todas API do sistema documentadas no padrão OPEN/API publicadas em algum lugar público ou com acesso fácil interno na empresa ?
    • Essas APIs são direcionadas ao negócio (não ao frontend, uma integração específica, tecnologia ou banco dados) ?
    • Essas APIs publicadas e documentadas atendem ao nível de maturidade REST: Level 1 - Resources ?
    • Essas APIs publicadas e documentadas atendem ao nível de maturidade REST: Level 2 - HTTP Verbs ?
    • No contexto de boas práticas levando em consideração o ebook backend - essas APIs estão de acordo com:
      • “Utilize os nomes de recurso no plural, seja instância ou coleção”
      • “Utilize verbos/métodos HTTP para identificar as operações sobre os recursos, conforme a tabela a seguir”
      • “Utilize o formato de objeto JSON para estruturar qualquer dado/Use JSON to Encode Structured Data”
      • “Utilize underscore (_) para separar palavras em parâmetros/Use snake_case (never camelCase) for Query Parameters”
      • “Utilize underscore (_) para separar palavras em nomes de campo/Property names must be ASCII snake_case (and never camelCase)”

Verde

• Contexto todos os repositório e todas as APIs desses repositórios (dos sistemas que possuem API REST)
  • O time possui todas API do sistema documentadas no padrão OPEN/API publicadas em algum lugar público ou com acesso fácil interno na empresa ?
    • Essas APIs são direcionadas ao negócio (não ao frontend, uma integração específica, tecnologia ou banco dados) ?
    • Essas APIs publicadas e documentadas atendem ao nível de maturidade REST: Level 1 - Resources ?
    • Essas APIs publicadas e documentadas atendem ao nível de maturidade REST: Level 2 - HTTP Verbs ?
    • No contexto de boas práticas levando em consideração o ebook backend - essas APIs estão de acordo com:
      • “Utilize os nomes de recurso no plural, seja instância ou coleção”
      • “Utilize verbos/métodos HTTP para identificar as operações sobre os recursos, conforme a tabela a seguir”
      • “Utilize o formato de objeto JSON para estruturar qualquer dado/Use JSON to Encode Structured Data”
      • “Utilize underscore (_) para separar palavras em parâmetros/Use snake_case (never camelCase) for Query Parameters”
      • “Utilize underscore (_) para separar palavras em nomes de campo/Property names must be ASCII snake_case (and never camelCase)”
• Contexto de um repositório e todas as APIs desse repositório (de um sistema que possua API REST)
  • Essa API publicada e documentada atende ao nível de maturidade REST: Level 3 - Hypermedia Controls
• Contexto de um repositório e uma API (de um sistema que possua API REST)
  • Essa API possui versionamento?

Azul

• Contexto todos os repositório e todas as APIs desses repositórios (dos sistemas que possuem API REST)
  • Essas APIs publicadas e documentadas atendem ao nível de maturidade REST: Level 3 - Hypermedia Controls
• Contexto de um repositório e todas as APIs desse repositório (de um sistema que possua API REST)
  • Esse repositório possui todas as APIs versionadas?