API HTTP+REST – Conceito e exemplo em Node.js

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, 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 esta 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 a 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 a 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) está operação é utilizada para buscar algo.

POST (Postar) está operação é utilizada para criar algo.

PUT  (Colocar) está operação é utilizada para criar e alterar algo.

DELETE (Deletar) está 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: www.json.org

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 estas 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

Assim para total compreendimento e exemplificação, mostrarei aqui como criar uma API disponibilizando as funções para manipular usuários de um blog fictício.

Pré-requisitos:

Neste tutorial, estou utilizando o Linux Ubuntu, mas ele também pode ser seguido sem problemas no Windows. Para este tutorial, é 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: https://nodejs.org/en/download/.

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 permite 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

Após  criarmos o arquivo package.json, vamos instalar as dependências do projeto. Para este tutorial vamos utilizar:

express –  O Express é um framework Node.JS que fornece vários recursos para o desenvolvimento de aplicações web com o Node.JS.

body-parser – O Body Parser é um Middleware para trabalharmos facilmente com o corpo das requisições.

fs –  O 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 estas dependências abra o terminal, acesse o diretório onde está o package.json, e utilize o comando:


npm install –save


Este 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. Após 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’);


Após isso iniciamos o Express é o atribuímos a variável app. Depois 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. Após isso utilize o comando:


npm start


Este comando irá 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 normal funcionamento.

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 possuí suas operações padrões. 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 devolva um JSON com os dados do usuário solicitado. Abra o arquivo server.js e cole no final dele o seguinte:

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 a nossa função de buscar usuário. Após isto 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. Após a 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 crie o novo usuário no arquivo e nos devolva 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 a nossa função de criar usuário. Após isto utilizamos o módulo File System para escrever no arquivo usuarios.json os dados enviados na requisição. Após 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 é seu ID ele edite o usuário no arquivo e nos devolva 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 a nossa função de editar usuário. Após isto 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 criarmos uma API que ao enviarmos um JSON com o ID do usuário ela delete o usuário no arquivo e nos devolva 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 a nossa função de deletar usuário. Após isto 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. Após isso utilize o comando npm start para iniciar nossa API.

Para testar nossa API, vamos utilizar o Postman que é um software que nos permite facilmente realizar uma requisição HTTP no formato que nossa API espera. Neste artigo não vou abordar aqui a instalação do Postman, veja no site oficial: https://www.getpostman.com/apps.

Após instalar o Postman, baixe o arquivo: API HTTP+REST – Conceito e exemplo em Node.js.postman_collection.json que 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.

Após isto abra as requisições, e teste a vontade. Veja que o arquivo usuarios.json será alterado conforme utilizamos as APIs.

O projeto criado neste artigo está disponível no GitHub: https://github.com/andersonirias/api-http-rest.

 

3 comentários em “API HTTP+REST – Conceito e exemplo em Node.js”

Deixe um comentário

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