SensediaSensediaSensediaSensedia
  • Products
    • API Management Platform
    • Governança de APIs
    • Event-Driven Architecture
    • Microservices & Service Mesh Architecture
    • PCI
    • Flexible Actions
  • Services
    • Consulting & Professional Services
    • API Care
    • Developer Experience
  • Solutions
    • Insurance
    • Open Banking
    • Retail & e-commerce
  • Content
    • Webinar e Ebooks
    • Blog
    • Cases
  • Contact
    • Customers
    • Support
  • Careers
  • Português
    • Inglês
    • Espanhol

Design de API REST: 7 dicas essenciais

By Ricardo Peloi | API | 5 comments | 25 agosto, 2016 | 10

Confira o Webinar API Design Restful

 

O Design de API REST em sua melhor versão

*atualizado em: 31 de março de 2020

Projetar um software pode ser complicado. Mas não precisa. Conheça as 7 principais dicas para garantir um excelente Design de API REST.

 

Fazer o Design de API REST nada mais é do que criar uma interface com regras bem definidas, disponibilizada para que seja possível realizar a interação com um sistema e obter suas informações ou realizar operações.

É como eu expliquei lá nos artigos de O Que são APIs: sua interface deve funcionar como um garçom em um restaurante: recebendo seus pedidos e retornando recursos (ou pratos), sem que os clientes precisem visitar a cozinha para ir pegar o prato lá.

As APIs RESTful ganharam uma enorme aceitação em todo o mundo, principalmente por seguir um padrão moderno e bem definido. Porém, o design de uma API RESTful pode sofrer desvios de padronização, o que de fato acontece, muitas vezes por falta de um conhecimento sólido dos conceitos.

Neste post, vamos conhecer algumas dicas que permitem criar um design aprimorado e padronizado daquilo que chamamos de uma verdadeira API no padrão RESTful.

E é claro, é sempre bom considerar que, ao fazer o Design da sua API REST, você também precisa ter em mente quem irá utilizá-la, como será utilizada dentro da sua estratégia, e também como será exposta ao mundo. Esse raciocínio, colocando a API em lugar privilegiado no seu planejamento, se chama API First.

Felizmente, temos conteúdos que pode te ajudar em todas essas etapas!

Utilize substantivos e não verbos

Uma das grandes falhas de padronização ao criar APIs RESTful estão relacionadas ao padrão dos endpoints criados (URLs de acesso aos serviços). O padrão RESTful exige que sejam utilizados substantivos e não verbos ou nomes de métodos. Por exemplo:

/getAllCustomers
/createNewCustomer
/deleteCustomer

Estas são formas incorretas de nomenclatura, que se assemelham a funções de alguma linguagem de programação orientada a objetos. Ao invés disso, para o Design mais adequado, utilize substantivos, como:

/customers
/customers/563

Use corretamente os métodos HTTP

O princípio fundamental do REST consiste em separar sua API em recursos lógicos. Esses recursos são manipulados utilizando requisições HTTP com os métodos GET, POST, PUT e DELETE.

Por exemplo, ao realizar uma requisição ao recurso /customers/563 utilizando o método GET, você estará solicitando que seja recuperado um cliente específico com o código 563.

Da mesma forma, ao realizar a mesma requisição (ou seja, no endpoint /customers/536), utilizando o método DELETE, você estará realizando uma exclusão de um cliente específico, de código 563.

Utilize nomes no plural

O nome do endpoint deve estar no singular ou no plural?

Esta é uma pergunta que costuma gerar muita discussão no Design de APIs RESTful.

De modo geral, cabe a você escolher. Particularmente, prefiro os nomes no plural, já que indicam um conjunto de recursos (como no caso dos clientes, acima).

Porém, uma coisa é certa: não faça mistura de endpoints no singular e no plural. A recomendação é que você simplifique e utilize todos os nomes no plural.

Utilize sub-recursos para os relacionamentos

Existem situações em que um recurso está relacionado a outro. É comum quando há uma hierarquia de objetos e recursos.

Por exemplo, se fosse uma API que retorna dados estatísticos sobre a geografia de um país, poderia existir sub-recursos para estados, dentro do país e municípios dentro dos estados.

Quando for o caso, utilize sub-recursos nos endpoints.

Por exemplo, a requisição

GET /customers/231/projects/

deve retornar a lista de projetos do cliente 231. Já a requisição

GET /customers/231/projects/4

deve retorna o projeto #4 do cliente 231.

Não altere estados com o método GET

Ao realizar operações que alteram o estado de um objeto, utilize preferencialmente os métodos POST, PUT e DELETE.

O método GET, como é intuitivo pelo nome, deve retornar apenas uma versão de leitura do recurso.

O HTTP oferece outros métodos para realizar escrita nos recursos, então use-os adequadamente. Nesse ponto, é importante lembrar das permissões e questões de Segurança de APIs, que já falamos nesse Webinar, o que nos leva ao nosso próximo tópico:

Utilize criptografia SSL

Sua API RESTful deve necessariamente utilizar criptografia SSL.

Como a sua API web pode ser acessada de qualquer lugar onde haja acesso à Internet, como uma praça de alimentação de um shopping center, uma livraria, um café ou um aeroporto, a preocupação em garantir um acesso seguro aos dados e serviços que sua API oferecem é sua.

Porém, nem todos esses locais conferem acesso seguro e criptografado.

Ter as informações que trafegam criptografadas é algo essencial. Além disso, utilizar SSL com tokens facilita a autenticação entre requisições, evitando-se que a cada requisição seja realizada nova autenticação.

Novamente, uma boa referência para estudar esse assunto é o Webinar de Segurança de APIs.

Crie versões para sua API

Como todo software, APIs devem crescer e evoluir. Por mais cuidadoso e experiente que você seja, sua API não será perfeita na primeira versão.

E nem precisa! Muitas vezes, é melhor expor a primeira versão da sua API e ir evoluindo-a aos poucos. Porém, tome cuidado em não alterar muito o seu design e acabar quebrando as aplicações que usavam as versões anteriores (como o Jeremiah Lee, do Fitbit, disse na entrevista para o Kleber, nosso CEO).

Portanto, ao criar uma nova versão para a sua API, garanta que a versão anterior ainda esteja disponível, não quebrando assim as funcionalidades de sistemas. Depois de comunicar as mudanças aos desenvolvedores, e dar um tempo de adaptação, versões antigas podem ser descontinuadas, ou você pode mantê-las no ar, sem oferecer suporte.

Garanta o sucesso da sua API RESTful!

Os 7 passos acima garantirão que o onboarding (começo do uso da sua API, por parte dos desenvolvedores) da sua API seja bem mais fácil!

Uma dica final é você ficar de olho na usabilidade da sua API, confira Como medir a usabilidade de uma API.

design de APIs, listas, RESTful, Webinars

Ricardo Peloi

Estuda Engenharia de Computação na Unicamp, é entusiasta por tecnologia, ciência e produtividade. Entre um post e outro no blog, tenta juntar as pontas soltas da vida com APIs =)

More posts by Ricardo Peloi

Related Post

  • Como expor APIs na prática – Parte 1

    By Petterson Andrade | 1 comment

    Confira nosso vídeo abaixo sobre Design de APIs: Mais do que algumas linhas de código! Expor APIs tornou-se uma necessidade que supera a troca de informações entre máquinas. Estamos na Economia de APIs. Negócios sãoRead more

  • Modelo de Maturidade da Arquitetura de APIs

    By Rafael Rocha | 0 comment

    Post original: https://www.linkedin.com/pulse/api-architecture-maturity-model-rafael-rocha/   Sua empresa está pronta para a Economia das APIs? Esta é a reflexão que os arquitetos e estrategistas digitais devem fazer, caso desejem que sua empresa participe dessa nova API Economy. MasRead more

  • Sensedia GraphQL +BFF Pattern

    Usando o GraphQL como implementação do padrão BFF

    By Rafael Rocha | 0 comment

    link original: https://www.linkedin.com/pulse/using-graphql-bff-pattern-implementation-rafael-rocha/   Introdução   Estamos na era das APIs RESTful, esse tipo de estilo arquitetônico da API está no patamar de plena produtividade. Muitas plataformas suportam REST, e também a comunidade e aRead more

  • Time Sensedia em Paris no APIDays

    3 Trend Topics do APIdays – Paris 2018

    By Rafael Rocha | 0 comment

    Quero compartilhar aqui com vocês alguns highlights e trend topics que percebemos no maior evento de APIs do mundo, o APIdays – por enquanto! porque nosso APIX está chegando junto! 😉 O evento aconteceu em Paris,Read more

  • Por que ter uma plataforma de Gerenciamento de APIs no seu negócio e como escolher a melhor

    By Ricardo Peloi | 2 comments

    Traduzido de Forrester Plataforma de Gerenciamento de APIs? Que plataforma? Você já deve saber que estamos vivendo a Era das APIs. Porém, não é só abrir seus dados e correr para o abraço. Uma camadaRead more

5 comments

  • Rodrigo Leite Responder 13 de setembro de 2016 at 20:06

    Muito bom o artigo. Já me deparei com endpoint escritos /getAlgumaCoisa ou /getTodosXPTO. 🙂
    Parabéns.

  • Tiago Freire Responder 21 de março de 2017 at 08:29

    Parabéns pelo artigo! muito bom!

  • Rodrigo Campos Responder 24 de janeiro de 2019 at 12:06

    Parabéns garoto!!! Muito bom!

  • Rafael Mota Responder 16 de setembro de 2020 at 16:08

    Por favor, me tira uma dúvida. Em casos que é necessário acessar um recurso de diversas formas, não só pelo Id. Qual a forma correta? Por exemplo, preciso acessar o recurso Produtos pelo Id, ou pela Descrição ou pela referência.
    Seria assim?
    /produtos/id/563
    /produtos/referencia/1a2b
    /produtos/descricao/televisao

    Parabéns pelo o artigo!

    • Lucas Tempestini Responder 21 de setembro de 2020 at 15:00

      Oi Rafael!

      Nesse caso, o recomendado é o uso de filtros (Filtering), que utiliza a seguinte sintaxe:
      /produtos?id=563
      /produtos?referencia=1a2b
      /produtos?descricao=televisao

      ou até mesmo com mais de um atributo na mesma consulta:
      /produtos?id=563&referencia=1a2b

      Lembrando que o seu backend precisa implementar esse comportamento de chamada da sua API. 🙂

Leave a Comment

Cancelar resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

Categorias

  • Analytics
  • API
  • Artigos
  • Eventos
  • Internet das Coisas
  • Negócios Digitais
  • Podcast Techbeer
  • Publicações externas
  • SOA

Tags

API API Economy API Experience API First API Management APIs APIX As APIs que você precisa conhecer Big Data Blocos Blocos de Construção Desenvolvedores desenvolvimento design de APIs digital transformation e-commerce Ecossistema de parceiros Estratégia API First Estratégia Digital Estratégias SaaS Eventos Exposição de APIs Forrester Games Gartner Gerenciamento de APIs Hackathon Inovação Integração Internet das Coisas Internet of Things IoT MicroServices midia Modelo de negócios Negócios Omnichannel open banking SaaS Segurança Segurança de APIs SOA Techbeer Tecnologia Transformação Digital

Posts recentes

  • Como criar um cluster Kubernetes com Terraform e AWS-EKS
  • Como o Developer Experience pode ajudar a suportar suas APIs
  • APIs e o novo paradigma da Educação Digital
  • Apache Ignite – Cache – Pt 1
  • Integração de gás com as APIs ganhando espaço
  • Política de Privacidade
Copyright © 2020 Sensedia | All Rights Reserved
  • Products
    • API Management Platform
    • Governança de APIs
    • Event-Driven Architecture
    • Microservices & Service Mesh Architecture
    • PCI
    • Flexible Actions
  • Services
    • Consulting & Professional Services
    • API Care
    • Developer Experience
  • Solutions
    • Insurance
    • Open Banking
    • Retail & e-commerce
  • Content
    • Webinar e Ebooks
    • Blog
    • Cases
  • Contact
    • Customers
    • Support
  • Careers
  • Português
    • Inglês
    • Espanhol
Sensedia