Nesta série de artigos vamos usar muitas tecnologias e conceitos para mostrar como criar uma API Restful usando a plataforma Node.js, o Express e acessando o MongoDB.

Se eu fosse entrar em detalhes em cada conceito e tecnologia usada neste artigo eu teria que escrever um livro e ainda assim creio que não esgotaria o assunto.

Assim, para tornar as coisas o mais simples possível, e acessível a maior parte de interessados, indepedente do nível de conhecimento, vou simplificar bastante e procurar ser o mais objetivo e claro que eu puder.

Vamos iniciar apresentando um pequeno resumo sobre os conceitos e tecnologias que serão usados durante a criação da nossa API Restful.

Embora essa apresentação inicial possa ser um pouco 'chata' ela é fundamental para quem esta começando agora.

Conceitos usados na criação da API Restful

1- HTTP - Hypertext Transfer Protocol

Conjunto de regras de transmissão de dados que permite que maquinas com diferentes configurações possam se comunicar usando um idioma comum.

É importante diferenciar os temos usados :

protocolo HTTP - Um protocolo da camada de aplicação OSI usado para transferência de dados.	http://
URL - Uniform Resource Locator  é o endereço de um recurso disponível em uma rede, seja a rede internet ou intranet.	macoratti.net
URN - Uniform Resource Name é um tipo de URI que usa o URN Scheme e que tem por objetivo a identificação única do recurso.	/api/produtos
URI - Uniform Resource Identifier é uma cadeia de caracteres compacta usada para identificar ou denominar um recurso na internet.	http://macoratti.net/api/produtos

Para mais detalhes sobre o protocolo http consulte: https://www.w3.org/Protocols/rfc2616/rfc2616.html

Dessa forma podemos dizer que a protocolo + URL + URN = URI => http:// + macoratti.net + /api/produtos

Toda a informação que transita no processo de enviar a requisição e obter a resposta possui dois componentes importantes: o Header e o Body.

HTTP Headers - São cabeçalhos da requisição/resposta ao servidor.(identificação do cliente, método da requisição, etc;)

HTTP Body - São os bytes de dados transmitidos em uma mensagem HTTP imediatamente após os cabeçalhos;

Toda requisição recebe um código de resposta conhecido como Status. Os códigos de status mais frequentes são :

Código	Significado
200 OK	A requisição foi bem sucedida
404 Not Found	O servidor não encontrou nenhuma URI correspondente.
500 Internal Server Error	O servidor não foi capaz de concluir a requisição devido a um erro inesperado
400 Bad Request	Possível falta de parâmetros requeridos na requisição
401 Unauthorized	Fata de parâmetros de autenticação

Para ver mais detalhes sobre os códigos de status veja : https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Para enviar e receber requisições, o protocolo HTTP utiliza métodos ou verbos que identificam qual a ação deve ser executada em um determinado recurso. A seguir temos os 5 verbos mais usados:

Verbos HTTP	Ação
GET	Solicita a apresentação de um recurso.
POST	As informações enviadas no corpo (body) da requisição são utilizadas para criar um novo recurso
PUT	Atualiza um recurso na URI especificada
DELETE	Remove um recurso. Deve retornar o status 204 caso não exista nenhum recurso para a URI especificada.

Para saber mais sobre os verbos http veja : https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

Esses verbos serão usados em nossa API para realizar as operações CRUD (Create, Read, Update e Delete).

2- Web Service

Um Web service é um conjunto de métodos acessados e invocados por outros programas utilizando tecnologias Web, sendo usado para transferir dados através de protocolos de comunicação para diferentes plataformas, independentemente das linguagens de programação utilizadas nessas plataformas.

Com esta tecnologia é possível que novas aplicações possam interagir com aquelas que já existiam e que sistemas desenvolvidos em plataformas diferentes sejam compatíveis.

Para que essa tarefa se concretizada com sucesso é necessário uma linguagem intermédia que garanta a comunicação entre a linguagem do Web service e o sistema que faz o pedido ao Web service. (Aqui é que entra o REST, SOAP, etc.)

Para mais detalhes sobre web services visite : https://pt.wikipedia.org/wiki/Web_service

3 -REST - Representational State Transfer

REST é um conjunto de princípios que definem como os padrões Web como HTTP e URIs devem ser usados.

Ele permite a comunicação/implementação com web services, se baseia no protocolo HTTP e permite utilizar vários formatos para representação de dados, como JSON (um dos mais utilizados), XML, RSS, entre outros. Lembrando que o REST é stateless, ou seja, não tem estado.

No 'padrão' REST a comunicação é feita usando os métodos HTTP, a URI e os recursos.  Os métodos usados são:

GET - Solicita informações de um recurso;
POST - Envia informações que são usadas para criar um novo recurso;
DELETE - Remove um recurso;
PUT - Atualiza um recurso na URI informada;

Não confundir REST com RestFul que é a capacidade de determinado sistema aplicar os princípios REST. Assim, Restful é a implementação do REST.

Para mais detalhes sobre REST veja : https://pt.wikipedia.org/wiki/REST

4- JSON - JavaScript Object Notation

É um formato de intercâmbio de dados abertos e baseado em texto que fornece um formato de troca de dados padronizado.

Os objetos JSON são definidos entre chaves { } e podem conter múltiplos pares nome : valor.  Exemplo:

var pessoa = { "nome" : "Jose Carlos" , "sobrenome" : "Macoratti" };
var produto = {"ProdutoID":1, "Descricao":"Notebook 14", "ProdutoNumero":"PRD-5381"};

JSON lembra XML :

JSON é texto simples
JSON é "auto-descritivo" (legível)
JSON é hierárquico (valores dentro de valores)
JSON pode ser analisado pelo JavaScript
JSON os dados podem ser transportadas usando AJAX

mas é diferente da XML:

Não utiliza a tag de fechamento
É mais curto e simples e leve
É mais rápido de ler e escrever
Pode ser analisado usando a função eval() do JavaScript
Utiliza matrizes
Não possui palavras reservadas
Possui parser nas principais linguagens e navegadores

5- Terminal de linha de comando (prompt de comando)

Vamos realizar muitas tarefas usando o terminal de linha de comando ou interpretador de linha de comando (vou chamar apenas de console) que é a aquela janela preta com o cursor piscando mostrada na figura abaixo:

Assim o interpretador de linha de comando ou console é um programa que fica lendo comandos de algum fluxo de dados. A cada comando lido, ele manda o computador executar o comando.

Funciona assim:

1. No prompt, você verá o cursor piscando.

2. Isso significa que você já pode digitar.

3. Depois de ter escolhido o comando, pressione Enter em seu teclado.

4. O comando será executado

Existem muitas maneiras de abrir uma janela de comando. No Windows 10, uma delas é usar o atalho Win+X :

•  Pressione Win+X para abrir o menu contextual e clique na opção Prompt de Comando ou Prompt de Comando (Admin).

Além dos comandos específicos do Node.js temos os comandos do DOS (Sistema Operacional) que são usados para gerenciar recursos como pastas e arquivos. Os comandos do DOS mais usados são:

Comando DOS	Ação
CHDIR ou CD	Muda o diretório corrente para outro a partir da pasta atual. Ex:  cd \teste
MKDIR  ou MD	Cria um diretório a partir da pasta corrente com o nome especificado. Ex:  md teste
RMDIR ou RD	Remove um diretório a partir da unidade corrente. Ex:  rd teste
RENAME ou REN	Permite ao usuário alterar o nome de um arquivo. Ex:  ren teste.txt teste.doc
TYPE	Permite exibir o conteúdo de determinado arquivo. Ex: type teste.txt
CLS	Limpa a tela.

Tecnologias/recursos usadas na criação da API Restful

A seguir vou relacionar os recursos que iremos utilizar na criação da nossa API Restful.

Recurso	Definição
Node.js	É uma plataforma para desenvolvimento de aplicações server-side baseadas em rede utilizando JavaScript e o V8 JavaScript Engine(Chrome). no servidor. http://nodejs.org
NPM	Gerenciador de módulos e pacotes NodeJS. (O nuget do Node)
Express.js	O Express é um framework para aplicações web para o Node.js, mínimo e flexível que fornece um conjunto robusto de recursos para aplicativos web e móvel.
MongoDB	Base de dados não SQL baseada em documentos (JSON) - http://mongodb.org
Mongoose	Mongoose é uma ferramenta de modelagem de objeto MongoDB projetada para trabalhar em um ambiente assíncrono. Interaje com o MongoDB.  http://mongoosejs.com
Body-Parser	Plugin ou Middleware Body-parser extrai a parte body de um fluxo de solicitação de entrada e o expõe via req.body. (Permite utilizar JSON).
Validator	Permite fazer validações da entrada do usuário(sanitizar).  http://validatorjs.org
Nodemon	Utilitário que monitora as alterações no código e reinicia o servidor
Postman	Postman - Permite realizar requisições HTTP GET, POST, PUT , DELETE, etc, a partir de uma interface simples e intuitiva, facilitando o teste e depuração de serviços REST. (Google Chrome)
VSCode	É um editor de código leve, multiplatafoma, gratuito e open source. Mantido pela Microsoft.  https://code.visualstudio.com/download

Para mais detalhes sobre o Visual Studio Code (VS Code) leia o artigo :  Visual Studio Code - O Editor multiplataforma da Microsoft - Macoratti

Nota:  Você pode utilizar outro editor de textos com o qual esteja mais familiarizado.(Atom, Sublime, Web-Storm, Brackets, etc.). Nos artigos eu vou usar o VS Code.

Dessa forma temos uma apresentação resumida dos conceitos e tecnologias que iremos usar de forma que você tem uma visão geral de tudo oque iremos abordar nesta série de artigos.