API
Uma API (Application Programming Interface), em português “Interface de Programação de Aplicativos”, é um conjunto de funções estabelecidas por um software, que funcionam como uma interface intermediária, para a utilização de funcionalidades deste software por aplicações externas.
Por exemplo: você tem uma loja online, e para que um cliente seu realize uma compra, ele deve se cadastrar em sua loja. No formulário de cadastro da sua loja, existe a opção de cadastrar utilizando o Facebook. Quando seu cliente utiliza essa opção, sua loja precisa pegar os dados deste cliente no Facebook para concluir o cadastro.
Para que seja possível sua loja pegar os dados do cliente, o Facebook disponibiliza uma API que é uma intermediadora da função de buscar dados de um usuário do Facebook.
HTTP
O HTTP (Hypertext Transfer Protocol), em português Protocolo de Transferência de Hipertexto, é um protocolo para transferência de arquivos hipermídia, como o HTML, por exemplo. Ele foi criado para a comunicação de navegadores web e servidores, mas também pode ser empregado em outras finalidades.
Ele trabalha com o modelo cliente-servidor – o cliente abre a conexão, faz uma requisição ao servidor e aguarda até receber uma resposta. Ele é um protocolo stateless, ou seja, o servidor não armazena informações entre as requisições. Para ler mais sobre o assunto acesse o site do W3C.
Por exemplo: ao acessar o site: http://irias.com.br, você está abrindo uma conexão com o servidor onde este site está hospedado, e está fazendo uma requisição à sua página inicial. Quando o navegador recebe a resposta do servidor, que é uma página HTML, ele faz sua renderização na tela.
Este processo é realizado utilizando o protocolo HTTP. Na URL do site (http://irias.com.br), a parte: http:// informa que é utilizado o protocolo HTTP.
REST
O REST (Representational State Transfer) é um estilo de arquitetura de software que define um conjunto de regras a serem utilizadas para a criação de serviços da internet. Os serviços da internet que utilizam o estilo de arquitetura REST fornecem um modo de se comunicar de forma transparente entre sistemas computacionais na internet.
Em um serviço da internet REST, as requisições são feitas à URI de um recurso, e esperam obter uma resposta que pode ser em diversos formatos, como: HTML, XML, JSON entre outros.
A resposta pode ser uma confirmação de uma alteração ou mesmo documentos solicitados. Quando o protocolo HTTP é utilizado, o que é mais comum, as operações disponíveis, são: GET, POST, PUT, DELETE.
- GET (Pegar): essa operação é utilizada para buscar algo
- POST (Postar): essa operação é utilizada para criar algo
- PUT (Colocar): essa operação é utilizada para criar e alterar algo
- DELETE (Deletar): essa operação é utilizada para deletar algo
JSON
O JSON (JavaScript Object Notation) é um formato leve de troca de dados. Ele é texto escrito com notação de objeto JavaScript. O JSON não é um formato exclusivamente utilizado pelo JavaScript. Ele pode ser utilizado em diversas linguagens de programação.
Assim, este formato está cada vez mais sendo utilizado para a comunicação entre sistemas diferentes, pois funciona como um formato universal que pode ser interpretado por sistemas que utilizam de linguagens de programação diferentes.
Exemplo de arquivo JSON:
{
“usuarios”:[
{
“nome”:”Primeiro usuário”,
“site”:”www.primeirousuario.com.br”,
“usuario_id”:1
},
{
“nome”:”Segundo usuário”,
“site”:”www.segundousuario.com.br”,
“usuario_id”:2
}
]
}Neste exemplo temos uma matriz chamada usuários, que possui dois usuários. Cada usuário possui um nome, site e usuario id. Para mais informações sobre JSON, acesse o site:
Resumindo
Em resumo, uma API é a forma de um sistema disponibilizar suas funções para serem utilizadas por aplicações externas. O protocolo HTTP, permite disponibilizar essas funções para que sejam acessadas pela internet.
O estilo de arquitetura REST, define regras que possibilitam a comunicação com as funções que foram disponibilizadas na internet. Os dados da comunicação são trafegados em formato JSON, que pode ser utilizado por diferentes linguagens de programação.
Exemplo com Node.JS em 10 passos
Para total compreendimento e exemplificação, mostrarei aqui como criar uma API disponibilizando as funções para manipular usuários de um site fictício.
Pré-requisitos:
Para este artigo estou utilizando o Linux Ubuntu, mas ele também pode ser seguido sem problemas no Windows. Para este passo a passo é necessário ter o Node.Js e o NPM instalados em seu computador. Não irei abordar a fundo a instalação de ambos.
Para download e instalação acesse o link oficial:
1. Iniciar o projeto
Para iniciar o projeto vamos criar o arquivo package.json. Este arquivo possui vários metadados relevantes para o projeto. Este arquivo é utilizado para fornecer informações que permitem identificar o projeto e trabalhar com suas dependências, então abra seu arquivo package.json e cole o seguinte conteúdo nele:
{
“name”: “api-http-rest”,
“version”: “1.0.0”,
“description”: “Exemplo prático do artigo: \”API HTTP+REST – Conceito e exemplo em Node.js\””,
“main”: “server.js”,
“scripts”: {
“test”: “echo \”Error: no test specified\” && exit 1″
},
“author”: “Anderson Irias”,
“license”: “ISC”,
“dependencies”: {
“body-parser”: “^1.18.3”,
“express”: “^4.16.4”,
“fs”: “0.0.1-security”
}
}2. Instalar dependências
Depois de criarmos o arquivo package.json, vamos instalar as dependências do projeto. Vamos utilizar:
- express: Express é um framework Node.JS que fornece vários recursos para o desenvolvimento de aplicações web com o Node.JS
- body-parser: Body Parser é um Middleware para trabalharmos facilmente com o corpo das requisições
- fs: File System é um módulo para trabalharmos com arquivos. Com ele é possível criar, ler, atualizar, renomear e deletar arquivos em nosso computador.
Para instalar essas dependências abra o terminal, acesse o diretório onde está o package.json, e utilize o comando:
npm install –saveEste comando vai ler nosso arquivo packge.json, e irá baixar as dependências nele listadas para o nosso projeto.
3. Criar o servidor web
Um servidor web é um software que pode servir conteúdo para a internet. Um servidor web processa solicitações de rede recebidas por HTTP e vários outros protocolos relacionados.
Como se trata de um exemplo simples, nosso projeto conterá somente um arquivo com toda a codificação. No mesmo diretório onde se encontra o arquivo packge.json vamos criar o arquivo server.js. Depois de criar o arquivo server.js, cole o seguinte conteúdo nele:
var express = require(‘express’);
var bodyParser = require(‘body-parser’);
var fs = require(‘fs’);
var app = express();
app.use(bodyParser.urlencoded({ extended:true }));
app.use(bodyParser.json());
app.use(function(req, res, next){
res.setHeader(“Access-Control-Allow-Origin”, “*”);
res.setHeader(“Access-Control-Allow-Methods”, “GET, POST, PUT, DELETE”);
res.setHeader(“Access-Control-Allow-Headers”, “content-type”);
res.setHeader(“Content-Type”, “application/json”);
res.setHeader(“Access-Control-Allow-Credentials”, true);
next();
});
app.listen(9090, function(){ console.log(‘Servidor Web rodando na porta 9090’) });Nas três primeiras linhas estamos incluindo as dependências que já foram baixadas para o nosso projeto.
var express = require(‘express’);
var bodyParser = require(‘body-parser’);
var fs = require(‘fs’);Em seguida iniciamos o Express e o atribuímos à variável app e configuramos o middleware Body Parser para ser utilizado com o Express, para ele poder tratar o corpo JSON das requisições que serão realizadas ao servidor.
var app = express();
app.use(bodyParser.urlencoded({ extended:true}));
app.use(bodyParser.json());Depois temos uma função para setar o cabeçalho HTTP padrão para as respostas que o nosso servidor retornará.
app.use(function(req, res, next){
res.setHeader(“Access-Control-Allow-Origin”, “*”);
res.setHeader(“Access-Control-Allow-Methods”, “GET, POST, PUT, DELETE”);
res.setHeader(“Access-Control-Allow-Headers”, “content-type”);
res.setHeader(“Content-Type”, “application/json”);
res.setHeader(“Access-Control-Allow-Credentials”, true);
next();
});Por fim vamos falar que nosso servidor vai escutar na porta 9090.
app.listen(9090, function(){ console.log(‘Servidor Web rodando na porta 9090’) });4. Testar o funcionamento do servidor web
Para testarmos o funcionamento do servidor web, acesse via terminal o diretório onde se encontram o arquivo packge.json e o server.js. Feito isso, utilize o comando:
npm startEste comando vai dar um start em nosso projeto e colocar o servidor web no ar. Caso não retorne nenhum erro, indica que nosso servidor web está no ar em funcionamento normal.
5. Base de dados
Para que nosso exemplo não fique muito complexo, ao invés de utilizar um banco de dados para guardar os dados do usuário, vamos utilizar um arquivo JSON. Crie o arquivo usuarios.json e cole o seguinte conteúdo nele:
{
“usuarios”:[
{
“nome”:”Primeiro usuário”,
“site”:”www.primeirousuario.com.br”,
“usuario_id”:1
},
{
“nome”:”Segundo usuário”,
“site”:”www.segundousuario.com.br”,
“usuario_id”:2
},
{
“nome”:”Terceiro usuário”,
“site”:”www.terceirousuario.com.br”,
“usuario_id”:3
}
]
}Neste JSON, temos uma matriz com três usuários. Cada usuário possui um nome, site e usuario id.
6. Função buscar usuário
Como vimos anteriormente, o HTTP possui suas operações padrão. Para criarmos a função de buscar um usuário, vamos utilizar o GET para criarmos uma API que, ao passarmos o ID do usuário, ela nos devolve um JSON com os dados do usuário solicitado.
Abra o arquivo server.js e cole no final dele o seguinte código:
app.get(‘/api’, function(req, res){
fs.readFile(‘usuarios.json’, ‘utf8’, function(err, data){
if (err) {
var response = {status: ‘falha’, resultado: err};
res.json(response);
} else {
var obj = JSON.parse(data);
var result = ‘Nenhum usuário foi encontrado’;
obj.usuarios.forEach(function(usuario) {
if (usuario != null) {
if (usuario.usuario_id == req.query.usuario_id) {
result = usuario;
}
}
});
var response = {status: ‘sucesso’, resultado: result};
res.json(response);
}
});
});No código acima estamos utilizando a função get do Express para criarmos uma rota e disponibilizar através da URL: http://localhost:9090/api o acesso via GET à nossa função de buscar usuário.
Depois utilizamos o módulo File System para abrir o arquivo usuarios.json e procurar nele os dados do usuário através do ID que foi informado na requisição GET. Depois da busca retornamos o resultado com os dados do usuário ou informando que o usuário não foi encontrado.
7. Função criar usuário
Para criarmos a função de criar um usuário vamos utilizar o POST para criarmos uma API que ao enviarmos um JSON com os dados do novo usuário ela cria o novo usuário no arquivo e nos devolve um JSON com o resultado da operação. Abra o arquivo server.js e cole no final dele o seguinte:
app.post(‘/api’, function(req, res){
fs.readFile(‘usuarios.json’, ‘utf8’, function(err, data){
if (err) {
var response = {status: ‘falha’, resultado: err};
res.json(response);
} else {
var obj = JSON.parse(data);
req.body.usuario_id = obj.usuarios.length + 1;
obj.usuarios.push(req.body);
fs.writeFile(‘usuarios.json’, JSON.stringify(obj), function(err) {
if (err) {
var response = {status: ‘falha’, resultado: err};
res.json(response);
} else {
var response = {status: ‘sucesso’, resultado: ‘Registro incluso com sucesso’};
res.json(response);
}
});
}
});
});No código acima estamos utilizando a função post do Express para criarmos uma rota e disponibilizar através da URL: http://localhost:9090/api o acesso via POST à nossa função de criar usuário.
Feito isso utilizamos o módulo File System para escrever no arquivo usuarios.json os dados enviados na requisição. Depois de escrever o novo usuário no arquivo, retornamos o resultado informando se o usuário foi criado ou não.
8. Função editar usuário
Para criarmos a função de editar um usuário, vamos utilizar o PUT para criarmos uma API que ao enviarmos um JSON com os novos dados do usuário e seu ID, ele poderá editar o usuário no arquivo e nos devolver um JSON com o resultado da operação. Abra o arquivo server.js e cole no final dele o seguinte:
app.put(‘/api’, function(req, res){
fs.readFile(‘usuarios.json’, ‘utf8’, function(err, data){
if (err) {
var response = {status: ‘falha’, resultado: err};
res.json(response);
} else {
var obj = JSON.parse(data);
obj.usuarios[(req.body.usuario_id – 1)].nome = req.body.nome;
obj.usuarios[(req.body.usuario_id – 1)].site = req.body.site;
fs.writeFile(‘usuarios.json’, JSON.stringify(obj), function(err) {
if (err) {
var response = {status: ‘falha’, resultado: err};
res.json(response);
} else {
var response = {status: ‘sucesso’, resultado: ‘Registro editado com sucesso’};
res.json(response);
}
});
}
});
});No código acima estamos utilizando a função put do Express para criarmos uma rota e disponibilizar através da URL http://localhost:9090/api o acesso via PUT à nossa função de editar usuário.
Depois disso utilizamos o módulo File System para ler e re-escrever no arquivo usuarios.json os dados enviados na requisição. Após editar o usuário no arquivo, retornamos o resultado informando se o usuário foi editado ou não.
9. Função deletar usuário
Para criarmos a função de deletar um usuário vamos utilizar o DELETE para criar uma API que, ao enviarmos um JSON com o ID do usuário, ela possa deletar o usuário no arquivo e nos devolver um JSON com o resultado da operação. Abra o arquivo server.js e cole no final dele o seguinte:
app.delete(‘/api’, function(req, res){
fs.readFile(‘usuarios.json’, ‘utf8’, function(err, data){
if (err) {
var response = {status: ‘falha’, resultado: err};
res.json(response);
} else {
var obj = JSON.parse(data);
delete obj.usuarios[(req.body.usuario_id – 1)];
fs.writeFile(‘usuarios.json’, JSON.stringify(obj), function(err) {
if (err) {
var response = {status: ‘falha’, resultado: err};
res.json(response);
} else {
var response = {status: ‘sucesso’, resultado: ‘Registro excluído com sucesso’};
res.json(response);
}
});
}
});
});No código acima estamos utilizando a função delete do Express para criarmos uma rota e disponibilizar através da URL: http://localhost:9090/api o acesso via DELETE à nossa função de deletar usuário.
Em seguida utilizamos o módulo File System para deletar no arquivo usuarios.json o usuário do ID informado. Após deletar o usuário no arquivo, retornamos o resultado informando se o usuário foi deletado ou não.
10. Testar o funcionamento da nossa API
Acesse via terminal o diretório onde se encontram o arquivo packge.json e o server.js. Depois disso utilize o comando npm start para iniciar nossa API.
Para testar nossa API vamos utilizar o Postman, um software que nos permite facilmente realizar uma requisição HTTP no formato que nossa API espera. Neste artigo não vou abordar a instalação do Postman – veja no site oficial:
Depois de instalar o Postman, baixe o arquivo: API HTTP+REST – Conceito e exemplo em Node.js.postman_collection.json, eles são as requisições que precisaremos para os testes. Abra o Postman e no menu está disponível a opção para importar o arquivo que foi baixado.
Depois disso abra as requisições e teste à vontade. Veja que o arquivo usuarios.json será alterado conforme utilizamos as APIs.
O projeto criado neste artigo está disponível no GitHub:
De 0 a 10, o quanto você recomendaria este artigo para um amigo?