Glossário API REST
Este artigo tem como objetivo fornecer um glossário de termos comuns que podem ser encontrados ao utilizar nossa API REST. Ao compreender esses termos, você poderá ter uma melhor compreensão do funcionamento da API e, assim, utilizar seus recursos de forma mais eficiente.
API
API significa "Application Programming Interface", uma sigla que pode não ser autoexplicativa. De maneira simples, uma API recebe solicitações de entrada e envia respostas de saída. Quando você faz uma solicitação à API, ela passa a solicitação para um servidor, que processa a solicitação e retorna uma resposta. Assim como a interface de usuário (UI) de um aplicativo permite que os usuários interajam com ele, uma interface de programação de aplicativo (API) permite que os clientes interajam com o aplicativo, fornecendo acesso a suas funcionalidades e recursos. Portanto, a API é apenas mais uma maneira de interagir com o sistema, oferecendo uma interface simplificada para as operações necessárias.
REST
REST significa "REpresentational State Transfer". É um conjunto de princípios e restrições arquitetônicas que definem a maneira como as APIs devem ser projetadas para facilitar a interação entre os sistemas de software. Uma API RESTful adere a seis restrições arquitetônicas específicas que garantem que as solicitações sejam processadas de maneira eficiente, segura e consistente. Essas restrições incluem, entre outras coisas, o uso de uma arquitetura cliente-servidor, a separação entre a interface e a implementação do servidor, e o uso de recursos identificáveis com URLs únicas.
Adotar uma abordagem RESTful permite que as APIs sejam desenvolvidas de forma mais padronizada e interoperável, simplificando a integração entre sistemas. Além disso, as restrições arquitetônicas ajudam a tornar a interação com as APIs mais fácil e menos intensiva em recursos, proporcionando melhor escalabilidade e desempenho.
Para obter mais informações sobre REST e suas restrições arquitetônicas, consulte Transferência de estado representacional na Wikipedia ou outras fontes especializadas em desenvolvimento de software.
JSON
A API do SoftExpert Suite é uma API baseada em JSON, o que significa que ela aceita e retorna somente dados em formato JSON. O formato JSON (JavaScript Object Notation) é uma forma padrão para armazenar e transferir dados entre diferentes plataformas. Embora o nome faça referência ao JavaScript, o JSON pode ser facilmente utilizado com outras linguagens de programação. O JSON possui uma sintaxe estrita que deve ser seguida corretamente, incluindo o uso correto de vírgulas, dois-pontos, parênteses e chaves (). Para ilustrar a legibilidade do JSON, segue um exemplo de objeto JSON sintaticamente correto:
{
"nome": "João",
"sobrenome": "Silva",
"idade": 30,
"endereco": {
"rua": "Rua A",
"cidade": "São Paulo",
"estado": "SP"
},
"telefones": [
{
"tipo": "residencial",
"numero": "(11) 1111-1111"
},
{
"tipo": "celular",
"numero": "(11) 9999-9999"
}
]
}
CRUD
Create, Read, Update, Delete. Pense neles como verbos. Eles informam à API para criar, ler, atualizar ou excluir registros. Na Internet, os quatro verbos correspondem aos métodos de solicitação HTTP: GET (ler), PUT (atualizar), POST (criar), DELETE (excluir). Existem mais do que esses quatro métodos de solicitação, mas esses são os mais comuns. Uma solicitação GET (ler) é o método HTTP mais básico. Você o usa o tempo todo ao navegar na web. Por exemplo, quando você usa a pesquisa do Google, seu navegador faz uma solicitação GET após a outra.
Endpoint
Os endpoints são utilizados para realizar chamadas à API. Como o próprio nome sugere, um endpoint é um local específico que recebe solicitações da web. Uma API consiste em uma coleção de endpoints, cada um deles com suas próprias regras referentes às operações CRUD (Create, Read, Update e Delete). Ao compreender a funcionalidade dos endpoints e suas respectivas regras, é possível utilizar a API de forma mais eficaz e eficiente.
Códigos de status de resposta HTTP
Quando uma solicitação é feita para um endpoint, o servidor executa os seguintes passos:
- Analisa as informações enviadas na solicitação.
- Procura o recurso referenciado na solicitação.
- Verifica se o usuário tem permissão para acessar o recurso.
- Retorna uma resposta com um código de status HTTP.
Os códigos de status HTTP são agrupados em cinco categorias, cada uma com um significado específico:
- (100-199) Respostas informativas
- (200-299) Respostas bem-sucedidas
- (300-399) Redirecionamento
- (400-499) Erros do cliente
- (500-599) Erros do servidor
É importante lembrar que a lista de códigos de status HTTP não é definitiva e algumas empresas podem utilizar seu próprio conjunto de códigos. Caso encontre um novo código de status desconhecido, é importante verificar com a empresa o que significa o código correspondente. Para mais detalhes, consulte a Lista de códigos de status HTTP na Wikipedia.
Payload
Assim como um caminhão transporta uma carga de um lugar para outro, as solicitações HTTP transportam informações para uma API. As solicitações que criam ou atualizam registros existentes na API precisam carregar dados para a operação. Por exemplo, ao criar um cliente em um sistema de gerenciamento de vendas utilizando uma API, é necessário enviar as informações do cliente para a API. Essas informações são enviadas na carga útil da solicitação, no formato JSON ou em outro formato definido pela API. A API utiliza essas informações para criar o novo registro de cliente no sistema de gerenciamento de vendas.
URI
URI é a sigla em inglês para "Uniform Resource Identifier" (em português, Identificador Uniforme de Recursos). Trata-se de uma sequência de caracteres que identifica de maneira única um recurso na internet. Esses recursos podem ser páginas web, imagens, documentos, serviços, entre outros.
Os URIs são utilizados em diversos contextos, como em navegadores web para acessar páginas na internet, em APIs REST para identificar endpoints específicos, e em outras aplicações que precisam se comunicar com recursos disponíveis na rede. Um exemplo de URI é a URL (Uniform Resource Locator), que é um tipo específico de URI utilizado para identificar a localização de um recurso na internet.