Entenda o que é uma API REST, como ela funciona, quais métodos HTTP utiliza, quando aplicar, quais cuidados de segurança adotar e como documentar APIs com OpenAPI e Swagger.
Confira!
APIs estão na base da integração entre sistemas modernos. Sempre que uma aplicação consulta dados de outra plataforma, sincroniza cadastros, aciona uma automação, integra um dashboard ou conecta sistemas corporativos, existe alguma interface de comunicação envolvida.
Entre os modelos mais utilizados está a API REST, uma abordagem amplamente adotada em aplicações web, sistemas corporativos, plataformas em nuvem, aplicativos móveis, integrações entre back-ends e ferramentas de automação de infraestrutura.
Na prática, uma API REST permite que um sistema exponha recursos por meio de endereços acessíveis, geralmente utilizando HTTP ou HTTPS. Esses recursos podem representar clientes, usuários, chamados, equipamentos, câmeras, sites, endereços IP, interfaces de rede, contratos, eventos, alarmes ou qualquer entidade relevante para uma aplicação.
Apesar de ser comum associar REST a URLs, JSON e métodos como GET, POST, PUT e DELETE, REST não é apenas “uma API que usa HTTP”. REST é um estilo arquitetural. Ele define princípios de organização, comunicação e separação de responsabilidades entre cliente e servidor.
Este artigo explica o que é uma API REST, como ela funciona, quais conceitos precisam ser compreendidos, quando esse modelo faz sentido e quais cuidados devem ser adotados em ambientes corporativos e de infraestrutura digital.
O que é uma API?
API é a sigla para Application Programming Interface, ou Interface de Programação de Aplicações.
De forma simples, uma API é uma interface que permite que dois sistemas conversem entre si de maneira estruturada. Ela define regras de acesso, formatos de entrada, formatos de saída, métodos disponíveis, autenticação, permissões e padrões de resposta.
Uma API pode ser usada para integrar um ERP a um sistema financeiro, conectar uma plataforma de monitoramento a ativos de infraestrutura, sincronizar informações entre sistemas corporativos, consultar dados de inventário em uma plataforma IPAM/DCIM, integrar sistemas de segurança eletrônica ou permitir que scripts automatizem tarefas operacionais.
Por exemplo, uma aplicação poderia consultar um cliente específico usando uma chamada como:
GET /clientes/123E receber uma resposta estruturada:
{
"id": 123,
"nome": "Empresa Exemplo",
"status": "ativo"
}Nesse caso, o sistema cliente pediu ao servidor os dados do cliente com identificador 123. O servidor respondeu com uma representação daquele recurso.
O que significa REST?
REST significa Representational State Transfer. O termo foi definido por Roy Fielding em sua tese de doutorado sobre estilos arquiteturais e arquitetura da web.
REST não é uma linguagem de programação, não é um protocolo, não é um framework e não é uma ferramenta. REST é um estilo arquitetural para sistemas distribuídos.
Uma API REST organiza a comunicação em torno de recursos. Um recurso pode ser qualquer entidade relevante para o sistema: um cliente, um equipamento, uma interface de rede, um chamado, uma câmera, um contrato, um site, um endereço IP ou um evento.
Esses recursos são identificados por URIs e manipulados por meio de uma interface uniforme. Em APIs web, essa interface normalmente é implementada com HTTP ou HTTPS.
Na prática de mercado, quando alguém fala em API REST, geralmente está se referindo a uma API HTTP que expõe recursos por URLs ou URIs, utiliza métodos HTTP, retorna dados estruturados, trabalha de forma stateless, separa cliente e servidor e utiliza status codes HTTP para indicar o resultado das operações.
Nem toda API que usa HTTP é realmente RESTful em sentido rigoroso. Muitas APIs chamadas de REST são, na prática, APIs HTTP organizadas por endpoints. Mesmo assim, o termo “API REST” se consolidou no mercado para descrever esse padrão de integração.
Como uma API REST funciona?
Uma API REST funciona por meio de requisições e respostas.
O fluxo básico é:
1. Um cliente faz uma requisição para um servidor. 2. A requisição aponta para uma URI. 3. O método HTTP indica a intenção da operação. 4. Headers carregam metadados da requisição. 5. O corpo da requisição pode enviar dados. 6. O servidor processa a solicitação. 7. O servidor retorna uma resposta com status code, headers e, quando necessário, um corpo com dados.
Exemplo de requisição:
GET /api/clientes/123 HTTP/1.1
Host: exemplo.com
Accept: application/json
Authorization: Bearer token-de-acessoExemplo de resposta:
HTTP/1.1 200 OK
Content-Type: application/json{
"id": 123,
"nome": "Empresa Exemplo",
"status": "ativo"
}Nesse exemplo, GET indica uma consulta, /api/clientes/123 identifica o recurso, Accept: application/json informa que o cliente espera receber JSON, Authorization transporta a credencial de acesso, 200 OK indica sucesso e o corpo da resposta contém a representação do recurso consultado.
Recursos, endpoints e URIs
Para entender API REST, é essencial diferenciar alguns conceitos.
Recurso é a entidade ou conceito exposto pela API. Pode ser um cliente, contrato, ativo, usuário, equipamento, interface ou endereço IP.
URI é o identificador do recurso. É o caminho usado para localizar ou representar aquele recurso dentro da API.
Endpoint é o ponto de acesso da API. Em termos práticos, é uma combinação entre URI e operação disponível.
Path é o caminho dentro da URL. Query string é o conjunto de parâmetros enviados após o ponto de interrogação. Payload ou body é o corpo da requisição, usado para enviar dados em operações como criação ou atualização.
Exemplo:
https://api.exemplo.com/clientes/123?incluirContratos=true| Elemento | Exemplo |
| Protocolo | https |
| Host | api.exemplo.com |
| Recurso | clientes |
| Identificador | 123 |
| Query parameter | incluirContratos=true |
Uma boa API REST tende a organizar seus recursos por substantivos, não por verbos. Por exemplo, GET /clientes/123 é preferível a GET /buscarCliente?id=123, porque o primeiro modelo representa um recurso, enquanto o segundo se aproxima mais de uma chamada de função remota.
Métodos HTTP usados em APIs REST
APIs REST utilizam métodos HTTP para indicar a intenção da operação. Esses métodos possuem semântica própria.
| Método | Uso comum | Seguro? | Idempotente? | Exemplo |
| GET | Consultar recurso | Sim | Sim | GET /clientes/123 |
| POST | Criar recurso ou iniciar processamento | Não | Não | POST /clientes |
| PUT | Substituir um recurso | Não | Sim | PUT /clientes/123 |
| PATCH | Atualizar parcialmente um recurso | Não | Depende da implementação | PATCH /clientes/123 |
| DELETE | Remover um recurso | Não | Sim | DELETE /clientes/123 |
| OPTIONS | Consultar operações disponíveis | Sim | Sim | OPTIONS /clientes |
Um método seguro é aquele que não deve alterar o estado do servidor. Por isso, GET deve ser usado para consulta, não para executar ações que modifiquem dados.
Um método idempotente é aquele que pode ser repetido várias vezes com o mesmo efeito final. Por exemplo, se uma chamada DELETE /clientes/123 remove um cliente, repetir a mesma chamada não deveria remover outro cliente. O resultado final continua sendo o mesmo: aquele recurso não está mais disponível.
Um erro comum é tratar os métodos HTTP apenas como equivalentes diretos de CRUD. Essa associação é útil didaticamente, mas simplifica demais a semântica. Em uma API bem desenhada, o método HTTP deve respeitar o contrato do recurso, o comportamento esperado e a semântica da operação.
Status codes em APIs REST
Status codes HTTP informam o resultado da requisição. Eles são fundamentais para que o cliente entenda se a operação foi bem-sucedida, se houve erro de autenticação, se o recurso não foi encontrado ou se ocorreu uma falha no servidor.
| Código | Significado | Uso comum em APIs |
| 200 | OK | Requisição bem-sucedida |
| 201 | Created | Recurso criado com sucesso |
| 204 | No Content | Sucesso sem corpo na resposta |
| 400 | Bad Request | Requisição inválida |
| 401 | Unauthorized | Falta autenticação válida |
| 403 | Forbidden | Usuário autenticado, mas sem permissão |
| 404 | Not Found | Recurso não encontrado |
| 409 | Conflict | Conflito de estado ou regra de negócio |
| 422 | Unprocessable Content | Dados compreensíveis, mas semanticamente inválidos |
| 429 | Too Many Requests | Limite de requisições excedido |
| 500 | Internal Server Error | Erro interno no servidor |
| 503 | Service Unavailable | Serviço indisponível |
O uso correto de status codes reduz ambiguidades e facilita integrações. Uma API que retorna sempre 200 OK, mesmo em situações de erro, transfere para o cliente a responsabilidade de interpretar manualmente o conteúdo da resposta.
Em sistemas corporativos, isso dificulta troubleshooting, observabilidade, auditoria e automação.
JSON, XML e formatos de representação
APIs REST trabalham com representações de recursos. Uma representação é uma forma de descrever o estado de um recurso em determinado momento.
O formato mais comum em APIs modernas é o JSON, por ser leve, legível, amplamente suportado e adequado para aplicações web, mobile e integrações entre sistemas.
Exemplo de representação JSON:
{
"id": 101,
"nome": "SW-CORE-01",
"tipo": "switch",
"status": "ativo"
}Apesar disso, REST não exige JSON. Uma API REST pode usar outros formatos, como XML, HTML, YAML ou formatos específicos de domínio. O importante é que o formato esteja definido, documentado e indicado corretamente por headers como:
Content-Type: application/json
Accept: application/jsonXML ainda aparece em integrações legadas, sistemas governamentais, ambientes bancários, notas fiscais eletrônicas, SOAP e integrações corporativas mais antigas. JSON, por outro lado, tornou-se o padrão de fato para APIs web modernas.
API REST, RESTful e HTTP API: existe diferença?
Embora os termos sejam usados de forma parecida no mercado, eles não significam exatamente a mesma coisa.
| Termo | Significado prático |
| API HTTP | Qualquer API exposta por HTTP |
| API REST | API que busca seguir princípios REST |
| API RESTful | API mais aderente às constraints do estilo REST |
| RPC via HTTP | API que usa HTTP como transporte, mas modela chamadas como funções |
| GraphQL | Modelo de API baseado em linguagem de consulta |
| SOAP | Protocolo mais rígido, geralmente associado a XML e WSDL |
Uma API pode usar HTTP e JSON sem ser verdadeiramente RESTful. Por exemplo, POST /executarBuscaCliente, POST /criarPedido e POST /atualizarStatusContrato representam ações e se aproximam de RPC. Já uma modelagem mais aderente a recursos seria GET /clientes/123, POST /pedidos e PATCH /contratos/456/status.
No uso cotidiano, muitas equipes chamam APIs HTTP bem organizadas de APIs REST, mesmo que não implementem todos os princípios REST em sentido estrito. Para fins práticos, o ponto central é: uma boa API REST deve ser previsível, bem documentada, segura, orientada a recursos e consistente em sua semântica.
REST vs SOAP vs GraphQL
REST não é o único modelo de integração. Em muitos ambientes, ele convive com SOAP, GraphQL, webhooks, filas, mensageria, gRPC e outros padrões.
| Critério | REST | SOAP | GraphQL |
| Modelo | Recursos | Operações e contratos formais | Consulta flexível |
| Formato comum | JSON | XML | JSON |
| Transporte | Normalmente HTTP/HTTPS | HTTP, SMTP e outros | Normalmente HTTP/HTTPS |
| Contrato | OpenAPI, documentação técnica | WSDL | Schema GraphQL |
| Uso comum | APIs web, integrações modernas, aplicações móveis | Sistemas legados, bancos, governo, integrações formais | Aplicações que precisam consultar dados flexíveis |
| Complexidade | Média | Alta | Média/alta |
REST costuma ser uma boa escolha quando os recursos são claros e a integração pode ser modelada de forma simples. SOAP ainda aparece em integrações formais e legadas. GraphQL pode ser interessante quando o cliente precisa buscar diferentes combinações de dados sem criar múltiplos endpoints específicos.
Quando usar API REST?
API REST faz sentido quando a organização precisa expor recursos de forma padronizada, interoperável e relativamente simples.
Ela é indicada quando sistemas precisam consultar e atualizar dados entre si, aplicações web e mobile precisam consumir dados de um back-end, sistemas internos precisam ser integrados, plataformas cloud precisam conversar com sistemas locais, ferramentas de automação precisam acessar inventários, eventos ou configurações e a documentação pode ser formalizada com OpenAPI.
Em uma arquitetura corporativa, APIs REST podem ser usadas para integrar ERP, CRM, sistemas de chamados, plataformas de monitoramento, ferramentas de inventário, sistemas de controle de acesso, plataformas de vídeo monitoramento, aplicações em nuvem, sistemas de gestão predial, ferramentas de automação de infraestrutura e painéis executivos.
Em ambientes de infraestrutura digital, uma API REST pode permitir que um sistema consulte ativos de rede, sites, racks, interfaces, endereços IP, VLANs, dispositivos, câmeras, alarmes ou eventos operacionais.
Quando REST pode não ser a melhor escolha?
REST é muito útil, mas não resolve todos os cenários.
Pode ser necessário avaliar alternativas quando a comunicação precisa ser bidirecional e em tempo real, o sistema exige streaming contínuo, o cliente precisa montar consultas altamente flexíveis, há necessidade de altíssima performance com payloads compactos, o domínio é fortemente orientado a eventos ou o ambiente exige contratos legados muito rígidos.
| Necessidade | Alternativa possível |
| Comunicação em tempo real | WebSocket |
| Eventos assíncronos | Filas, Kafka, RabbitMQ, MQTT |
| Consulta flexível de dados | GraphQL |
| Alta performance entre serviços | gRPC |
| Streaming | gRPC streaming, WebSocket, SSE |
| Integração legada formal | SOAP |
| Notificação de eventos | Webhooks |
A escolha da arquitetura deve considerar requisitos de negócio, segurança, latência, volume, governança, rastreabilidade e maturidade técnica da equipe.
Segurança em APIs REST
APIs REST precisam ser tratadas como superfícies de exposição. Uma API mal protegida pode permitir acesso indevido a dados, execução de operações não autorizadas, abuso de recursos computacionais ou vazamento de informações sensíveis.
Boas práticas essenciais incluem usar HTTPS, implementar autenticação adequada, aplicar autorização por recurso, validar entradas, limitar taxa de requisições, registrar logs, monitorar erros e consumo, controlar exposição de dados sensíveis, implementar versionamento, documentar endpoints ativos, remover APIs obsoletas, revisar permissões, proteger tokens e chaves de API e aplicar políticas de CORS quando necessário.
Um erro crítico é autenticar o usuário, mas não validar se ele pode acessar aquele objeto específico. Por exemplo, um usuário autenticado não deve conseguir consultar o recurso de outro cliente apenas alterando o ID na URL.
Esse tipo de falha é conhecido como problema de autorização em nível de objeto e é um dos riscos mais importantes em segurança de APIs.
Exemplo de risco:
GET /clientes/123
GET /clientes/124Se o usuário tem acesso apenas ao cliente 123, a API precisa impedir que ele consulte o cliente 124. Essa verificação não pode depender apenas da interface do usuário; precisa existir no back-end.
Documentação com OpenAPI e Swagger
Uma API sem documentação formal tende a gerar dependência de conhecimento informal. Isso dificulta integração, manutenção, testes, evolução, troubleshooting e onboarding de novos times.
A especificação OpenAPI permite descrever APIs HTTP de forma padronizada. Com ela, é possível documentar paths, métodos, parâmetros, headers, corpo de requisição, respostas, schemas, autenticação, exemplos, erros e versionamento.
Swagger é frequentemente usado como nome associado ao ecossistema de ferramentas para documentação, visualização e testes de APIs baseadas em OpenAPI.
Exemplo simplificado de documentação OpenAPI:
openapi: 3.0.3
info:
title: API de Clientes
version: 1.0.0
paths:
/clientes/{id}:
get:
summary: Consulta cliente por ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
"200":
description: Cliente encontrado
"404":
description: Cliente não encontradoEm ambientes corporativos, OpenAPI ajuda a transformar a API em contrato técnico. Isso reduz falhas de comunicação entre equipes de desenvolvimento, infraestrutura, segurança, operação e fornecedores.
Boas práticas de design de API REST
Uma API REST deve ser previsível. Quanto mais consistente for a modelagem, menor será o esforço de integração.
| Boa prática | Por que importa |
| Usar substantivos nos recursos | Mantém a modelagem orientada a entidades |
| Usar métodos HTTP corretamente | Evita ambiguidade semântica |
| Padronizar status codes | Facilita interpretação das respostas |
| Versionar a API | Reduz risco de quebra de compatibilidade |
| Documentar com OpenAPI | Cria contrato técnico claro |
| Implementar paginação | Evita respostas muito grandes |
| Oferecer filtros e ordenação | Melhora consumo dos dados |
| Padronizar mensagens de erro | Facilita diagnóstico |
| Aplicar autenticação e autorização | Protege dados e operações |
| Implementar rate limiting | Reduz abuso e indisponibilidade |
| Usar correlation IDs | Facilita rastreamento e troubleshooting |
| Registrar logs relevantes | Apoia auditoria e investigação |
| Evitar acoplamento com estrutura interna | Permite evolução do sistema |
Exemplo de recurso bem modelado:
GET /ativos
GET /ativos/101
GET /ativos/101/interfaces
POST /ativos
PATCH /ativos/101
DELETE /ativos/101Exemplo menos recomendado:
GET /buscarAtivo
POST /criarAtivo
POST /alterarAtivo
POST /deletarAtivoO segundo modelo funciona tecnicamente, mas se aproxima mais de chamadas remotas de função. Ele reduz a clareza semântica e tende a dificultar padronização.
Exemplo de API REST na prática
Imagine uma empresa que possui uma base de inventário de infraestrutura. Essa base registra switches, firewalls, servidores, access points, câmeras, racks, interfaces, endereços IP, VLANs e sites.
Uma API REST poderia expor esses recursos para integração com ferramentas de monitoramento, dashboards, automações e sistemas de documentação.
Exemplos de endpoints:
GET /ativos
GET /ativos/101
GET /ativos/101/interfaces
GET /sites
GET /sites/5/racks
GET /vlans
POST /ativos
PATCH /ativos/101Exemplo de resposta:
{
"id": 101,
"nome": "SW-CORE-01",
"tipo": "switch",
"fabricante": "Cisco",
"site": "Data Center",
"rack": "RACK-01",
"status": "ativo",
"interfaces": [
{
"nome": "Gi1/0/1",
"velocidade": "1Gbps",
"status": "up",
"vlan": 10
}
]
}Com esse tipo de API, um sistema externo poderia consultar ativos, validar endereços IP disponíveis, atualizar status operacional, alimentar dashboards, correlacionar eventos de monitoramento, cruzar dados de rede com dados físicos, automatizar documentação e integrar inventário com sistemas de chamados.
Esse exemplo mostra que API REST não é apenas um assunto de desenvolvimento de software. Ela também é uma peça importante em arquitetura de infraestrutura digital.
API REST em infraestrutura digital e engenharia de sistemas
Em ambientes críticos, APIs devem ser tratadas como componentes de arquitetura. Elas conectam sistemas, transportam dados operacionais, suportam automações e podem impactar diretamente disponibilidade, segurança e continuidade.
Uma API REST pode participar da integração entre plataformas de monitoramento, sistemas IPAM/DCIM, ferramentas de automação, ambientes cloud, sistemas de segurança eletrônica, plataformas de vídeo monitoramento, controle de acesso, alarmes, dashboards operacionais, sistemas corporativos, ERPs, CRMs, bases de ativos e sistemas de chamados.
Em uma arquitetura madura, APIs precisam ter governança. Isso inclui documentação, controle de versão, autenticação, autorização, observabilidade, inventário, ciclo de vida, testes e critérios de disponibilidade.
Em projetos de engenharia de sistemas, a API deve ser avaliada como parte do ecossistema técnico, não como um detalhe isolado de software. Uma integração mal especificada pode gerar falhas operacionais, inconsistência de dados, dependência de fornecedores, retrabalho e riscos de segurança.
Por isso, em ambientes corporativos, uma API REST deve ser pensada com o mesmo rigor aplicado a redes, servidores, cloud, segurança e documentação técnica.
Erros comuns ao criar APIs REST
Alguns erros aparecem com frequência em projetos de APIs.
| Erro | Consequência |
| Criar endpoints como verbos | A API fica parecida com RPC e perde consistência |
| Ignorar status codes | O cliente não entende corretamente o resultado |
| Retornar sempre 200 OK | Erros ficam escondidos no corpo da resposta |
| Não versionar | Mudanças podem quebrar integrações existentes |
| Não documentar | A API depende de conhecimento informal |
| Não implementar paginação | Respostas podem ficar grandes e lentas |
| Expor dados demais | Aumenta risco de vazamento |
| Não validar autorização por objeto | Pode permitir acesso indevido |
| Não limitar requisições | Abre margem para abuso ou indisponibilidade |
| Não registrar logs | Dificulta auditoria e troubleshooting |
| Não monitorar erros | Problemas passam despercebidos |
| Não remover endpoints obsoletos | Aumenta superfície de ataque |
| Não padronizar mensagens de erro | Dificulta integração e suporte |
Uma API REST não deve ser avaliada apenas por “funcionar”. Ela deve ser clara, segura, documentada, observável e sustentável ao longo do tempo.
Conclusão
API REST é uma das formas mais utilizadas para integrar sistemas modernos. Ela combina simplicidade, interoperabilidade e aderência ao ecossistema web, sendo amplamente aplicada em aplicações corporativas, plataformas em nuvem, sistemas móveis, automações e ambientes de infraestrutura digital.
No entanto, uma API REST bem projetada não é apenas uma coleção de URLs. Ela exige modelagem correta de recursos, uso adequado de métodos HTTP, status codes coerentes, documentação formal, segurança, versionamento e governança.
Para empresas que dependem de sistemas integrados, infraestrutura crítica, cloud, segurança eletrônica, monitoramento e automação, APIs REST devem ser tratadas como parte da arquitetura técnica. Quando bem especificadas, elas reduzem retrabalho, aumentam interoperabilidade e permitem evolução controlada dos sistemas.
A A3A Consulting Engineering apoia empresas na arquitetura, integração e documentação de sistemas críticos, conectando infraestrutura digital, redes, cloud, segurança eletrônica e automação em ambientes corporativos.
Referências técnicas
[1] Roy Fielding. REST APIs must be hypertext-driven. Disponível em: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven.
[2] IETF. RFC 9110 — HTTP Semantics. Disponível em: https://www.rfc-editor.org/rfc/rfc9110.
[3] IETF. RFC 3986 — Uniform Resource Identifier: Generic Syntax. Disponível em: https://www.rfc-editor.org/rfc/rfc3986.
[4] IETF. RFC 8259 — The JavaScript Object Notation JSON Data Interchange Format. Disponível em: https://www.rfc-editor.org/rfc/rfc8259.
[5] OpenAPI Initiative. OpenAPI Specification. Disponível em: https://spec.openapis.org/oas/latest.html.
[6] OWASP Foundation. OWASP API Security Top 10. Disponível em: https://owasp.org/API-Security/editions/2023/en/0x00-header/.
[7] MDN Web Docs. HTTP request methods. Disponível em: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods.
[8] MDN Web Docs. HTTP response status codes. Disponível em: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status.
[9] Microsoft. Azure API Guidelines. Disponível em: https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md.
[10] NetBox Labs. NetBox REST API Documentation. Disponível em: https://netboxlabs.com/docs/netbox/en/stable/integrations/rest-api/.
[11] NetBox Labs. NetBox GraphQL API Documentation. Disponível em: https://netboxlabs.com/docs/netbox/en/stable/integrations/graphql-api/.
Perguntas frequentes
API REST é uma API baseada no estilo arquitetural REST, geralmente implementada sobre HTTP ou HTTPS. Ela organiza a comunicação em torno de recursos identificados por URIs e utiliza métodos como GET, POST, PUT, PATCH e DELETE para consultar ou manipular representações desses recursos.
API é qualquer interface que permite comunicação entre sistemas. API REST é um tipo específico de API que segue princípios do estilo REST, normalmente usando HTTP, URIs, métodos padronizados e representações como JSON.
Não. REST é um estilo arquitetural. HTTP é um protocolo frequentemente usado para implementar APIs REST.
Não. Uma API pode usar HTTP e JSON sem ser RESTful. Para ser mais aderente a REST, ela deve ser orientada a recursos, usar interface uniforme, comunicação stateless, representações bem definidas e reduzir acoplamento entre cliente e servidor.
Não. JSON é o formato mais comum em APIs modernas, mas REST não exige JSON. A API pode usar XML, HTML, YAML ou outros formatos, desde que a representação esteja definida e documentada.
Endpoint é um ponto de acesso da API. Na prática, é uma combinação entre uma URI e uma operação disponível. Por exemplo, GET /clientes/123 é um endpoint para consultar o cliente de ID 123.
URI é um identificador de recurso. URL é um tipo de URI que também indica como localizar o recurso. Em APIs REST, o termo URI costuma ser usado para indicar os caminhos que identificam recursos.
GET é usado para consultar recursos e não deve alterar o estado do servidor. POST é usado para criar recursos ou iniciar processamentos, dependendo do contrato da API.
PUT normalmente substitui a representação de um recurso. PATCH é usado para atualizações parciais. O comportamento exato deve ser definido pela documentação da API.
RESTful é um termo usado para indicar que uma API segue de forma mais consistente os princípios do estilo REST. No mercado, o termo também é usado de forma ampla para APIs HTTP bem organizadas.
Status code é o código HTTP retornado pelo servidor para indicar o resultado da requisição. Exemplos: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found e 500 Internal Server Error.
OpenAPI é uma especificação para descrever APIs HTTP de forma padronizada. Ela permite documentar endpoints, métodos, parâmetros, schemas, respostas, autenticação e exemplos.
Não exatamente. OpenAPI é a especificação. Swagger é um conjunto de ferramentas e um nome historicamente associado à documentação e visualização de APIs baseadas nessa especificação.
API REST pode ser segura, mas isso depende da implementação. É necessário usar HTTPS, autenticação, autorização por recurso, validação de entrada, rate limiting, logs, monitoramento e boas práticas de segurança.
REST costuma ser adequado quando os recursos são claros e a integração pode ser organizada por endpoints previsíveis. GraphQL pode ser melhor quando o cliente precisa consultar combinações muito flexíveis de dados em uma única chamada.
REST pode não ser a melhor escolha para comunicação em tempo real, streaming contínuo, altíssima performance entre serviços, arquitetura fortemente orientada a eventos ou integrações que exigem contratos legados rígidos.
