Projeto de APIs RESTful com NodeJS e Restify

Portuguese (Português) translation by Erick Patrick (you can also view the original English article)

Final product image — What You'll Be Creating

Uma API RESTful consiste de dois conceitos principais: Recurso e Representação. Um Recurso pode ser qualquer objeto associado a um dado ou identificado a uma URI (mais de uma URI pode referir-se a um mesmo recurso), e que pode ser operado usando métodos HTTP. Uma Representação é uma forma de apresentar um recurso. Neste tutorial, passaremos um conteúdo teórico sobre projetos de APIs RESTful e implementaremos uma API de blog, usando o NodeJS.

Recurso

Escolher os recursos corretos para uma API RESTful é uma parte importante do projeto. Primeiro de tudo, você precisa analisar o domínio do seu negócio e, depois, decidir quantos e quais recursos serão usados e que são relevantes às necessidades do seu negócio. Se você estiver projetando uma API para um blog, provavelmente usará recursos como Artigo, Usuário e Comentário. Esses são os nomes dos recursos e os dados associados a eles são o recurso em si:

{
"title": "Como Projetar uma API RESTful",
    "content": "Projeto de API RESTful é muito importante no mundo do desenvolvimento de software.",
    "author": "erickpatrick",
    "tags": [
        "technology",
        "nodejs",
        "node-restify"
        ]
    "category": "NodeJS"
}

Verbos de Recursos

Podemos prosseguir com a operação do recurso após decidir quais são os recursos obrigatório. Operações referem-se aos métodos HTTP. Por exemplo, para criarmos um artigo, podemos realizar a seguinte requisição:

POST /articles HTTP/1.1
Host: localhost:3000
Content-Type: application/json

{
  "title": "Projeto de API RESTful com Restify",
  "slug": "projeto-api-rest-restify",
  "content": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  "author": "erickpatrick"
}

Da mesma forma, podemos visualizar um artigo realizando a seguinte requisição:

1	GET /articles/123456789012 HTTP/1.1
2	Host: localhost:3000
3	Content-Type: application/json

E quanto a atualizar um artigo já existente? Sei muito bem o que você está pensando:

Posso realizar outra requisição POST em relação a /articles/update/123456789012 com os dados a serem atualizados.

Talvez, mas a URI está ficando um pouco mais complexa. Como disse mais cedo, as operações referem-se aos métodos HTTP. Isso significa que devemos apresentar a operação de atualização no método HTTP ao invés de colocá-lo na URI. Por exemplo:

PUT /articles/123456789012 HTTP/1.1
Host: localhost:3000
Content-Type: application/json
{
"title": "Como Projetar um API RESTful - Atualizada",
    "content": "Como Projetar um API RESTful - Atualizada - é muito importante no mundo do desenvolvimento de software.",
    "author": "erickpatrick",
    "tags": [
        "tecnologia",
        "nodejs",
        "restify",
        "outra tag"
        ]
    "category": "NodeJS"
}

Por falar em alterações, neste exemplo podemos ver campos de tags e categorias. Eles não são campos obrigatórios. Você pode deixá-los em branco e preenchê-los no futuro.

Algumas vezes, você precisa remover um artigo que esteja desatualizado. Nestes casos, você pode usar uma requisição HTTP do tipo DELETE em relação à URI /articles/123456789012.

Os métodos HTTP são conceitos padrões. Se usá-los como operações, você terá URIs mais simples e esse tipo de API simples ajudará você a obter clientes, clientes felizes.

E se você quisesse publicar um comentário em um artigo? Você pode selecionar o artigo e adicionar um comentário novo a ele. Com essa expressão em mente, você pode realizar a seguinte requisição:

POST /articles/123456789012/comments HTTP/1.1
Host: localhost:3000
Content-Type: application/json
{
"text": "Wow! Este é um ótimo tutorial",
    "author": "Zé niguém"
}

A forma de recurso acima é chamada de sub-recurso. Comentário é um sub-recurso de Artigo. Os Comentário e sua carga acima serão inseridos na base de dados como um filho de Artigo. Algumas vezes, uma URI diferente refere-se a uma mesmo recurso. Por exemplo, para ver um comentário específico, você pode usar tanto:

1	GET /articles/123456789012/comments/123 HTTP/1.1
2	Host: localhost:3000
3	Content-Type: application/json

ou:

1	GET /comments/123456789012 HTTP/1.1
2	Host: localhost:3000
3	Content-Type: application/json

Versionamento

Geralmente, funcionalidades de uma API alteram-se frequentemente, para que se possa oferecer novas funcionalidades aos clientes. Neste caso, duas versões de uma mesma API podem existir ao mesmo tempo. Para separá-las, você pode usar versionamento. Há duas formas de versionamento

Versão na URI: Você pode prover o número de versão na própria URI. Por exemplo, /v1.1/articles/123456789012.
Versão no Cabeçalho: Você pode prover o número da versão no cabeçalho e nunca precisar mudar a URI. Por exemplo:

1	GET /articles/123456789012 HTTP/1.1
2	Host: localhost:3000
3	Accept-Version: 1.0

Na verdade, a versão apenas altera a representação do recurso, não o conceito do recurso em si. Então, você não precisa alterar a estrutura do URI. Na v1.1, talvez um novo campo seja adicionado ao Artigo. Entretanto, ele ainda retorna um artigo. Na segunda opção, a URI continua simples e os clientes não precisam alterar as URIs em suas implementações.

É importante projetar uma estratégia para situações onde o cliente não provê um número de versão. Você pode lançar um erro quando um número de versão não é apresentado ou você pode retornar uma resposta usando a primeira versão. Se você usar a última versão estável como a versão padrão, os clientes podem obter vários erros em suas implementações.

Representação

A Representação é a forma como uma API apresenta um recurso. Ao invocar uma API através de uma URI, você receberá um recurso. Esse recurso pode estar em um formato como o XML, JSON, etc. É preferido o formato JSON caso esteja projetando uma nova API. Entretanto, se você estiver atualizando uma API já existente e que já é acostumada a retornar uma resposta XML, você pode prover outra versão com uma resposta em JSON.

Certo, deixemos a teoria sobre projetos de APIs RESTful de lado. Vejamos como projetar e implementar uma API para blogs usando o Restify.

API RESTful de um Blog

Projeto

Para projetarmos uma API RESTful, precisamos analisar o domínio do negócio. Só então podemos definir nossos recursos. Em uma API de blogs, precisamos:

Criar, Atualizar, Apagar e Visualizar um Artigo
Criar comentários para um Artigo específico, além de Atualizar, Apagar e Visualizar um Comentário
Criar, Atualizar, Apagar e Visualizar um Usuário

Nesta API, não cobrirei a parte de autenticação necessária para criar um artigo ou comentário. Para essa parte, você pode referir-se ao artigo Autenticação com Tokens Usando AngularJS & NodeJS.

Os nomes dos nossos recursos estão prontos. Operações de recursos são CRUD simples. Você pode referir-se à tabela a seguir para ter uma visualização geral da API.

Nome do Recurso	Verbos HTTP	Métodos HTTP
Artigo	criar Artigo, atualizar Artigo, remover Artigo, visualizar Artigo	POST /articles com os dados, PUT /articles/123 com os dados, DELETE /articles/123 e GET /article/123
Comentário	criar Comentário, atualizar Comentário, remover Comentário, visualizar Comentário	POST /articles/123/comments com os dados, PUT /comments/123 com os dados, DELETE /comments/123 e GET /comments/123
Usuário	criar Usuário, atualizar Usuário, remover Usuário, visualizar Usuário	POST /users com os dados, PUT /users/123 com os dados, DELETE /users/123 e GET /users/123

Configuração do Projeto

Neste projeto, usaremos o NodeJS com Restify. Os recursos serão salvos em uma base de dados MongoDB. Antes de tudo, devemos definir os recursos como modelos no Restify.

Artigo

var mongoose = require("mongoose");
var Schema   = mongoose.Schema;

var ArtigoSchema = new Schema({
title: String,
    slug: String,
    content: String,
    author: {
        type: String,
        ref: "Usuario"
    }
});
mongoose.model('Artigo', ArtigoSchema);

Comentários

var mongoose = require("mongoose");
var Schema   = mongoose.Schema;

var ComentarioSchema = new Schema({
text: String,
    article: {
        type: String,
        ref: "Artigo"
    },
    author: {
        type: String,
        ref: "Usuario"
    }
});
mongoose.model('Comentarios', ComentariosSchema);

Usuário

Não haverá operações para o recurso Usuário. Assumiremos que já sabemos o usuário atual que será capaz de operar os artigos ou comentários.

Você deve se perguntar de onde esse módulo mongoose vem. É o framework ORM para MongoDB escrito como módulo para NodeJS mais conhecido. Este módulo está incluso no projeto, dentro de outro arquivo de configuração.

Agora, podemos definir nossos verbos HTTP para os recursos acima. Você pode ver abaixo:

var restify = require('restify')
, fs = require('fs')


var controllers = {}
    , controllers_path = process.cwd() + '/app/controllers'
fs.readdirSync(controllers_path).forEach(function (file) {
    if (file.indexOf('.js') != -1) {
        controllers[file.split('.')[0]] = require(controllers_path + '/' + file)
    }
})

var server = restify.createServer();

server
    .use(restify.fullResponse())
    .use(restify.bodyParser())

// Início dos Artigos
server.post("/articles", controllers.article.createArtigo)
server.put("/articles/:id", controllers.article.updateArtigo)
server.del("/articles/:id", controllers.article.deleteArtigo)
server.get({path: "/articles/:id", version: "1.0.0"}, controllers.article.viewArtigo)
server.get({path: "/articles/:id", version: "2.0.0"}, controllers.article.viewArtigo_v2)
// Fim dos Artigos

// Início dos Comentarios
server.post("/comments", controllers.comment.createComentarios)
server.put("/comments/:id", controllers.comment.viewComentarios)
server.del("/comments/:id", controllers.comment.deleteComentarios)
server.get("/comments/:id", controllers.comment.viewComentarios)
// Fim dos Comentarios

var port = process.env.PORT || 3000;
server.listen(port, function (err) {
    if (err)
        console.error(err)
    else
        console.log('Aplicativo pronto na porta: ' + port)
})

if (process.env.environment == 'production')
    process.on('uncaughtException', function (err) {
        console.error(JSON.parse(JSON.stringify(err, ['stack', 'message', 'inner'], 2)))
    })

Neste trecho de código, a primeira coisa feita é iterar sobre todos os arquivos dos controladores e inicializá-los, para que uma requisição específica possa ser realizada. Após isso, URIs para operações específicas são definidas em relação às operações CRUD básicas. Também há versionamento para uma das operações em relação ao recurso Artigo.

Por exemplo, se você configurar a versão como sendo a 2 no cabeçalho Accept-Version, o método viewArtigo_v2 será executado. viewArtigo e viewArtigo_v2 realizam o mesmo trabalho, apresentando o recurso, mas mostram o recurso Artigo em formatos diferentes, como pode ser visto através do campo title, no exemplo abaixo. Finalmente, o servidor é iniciado numa porta específica, além da aplicação de alguns relatórios de erros. Podemos dar continuidade com os métodos dos controladores mapeados às operações HTTP em relação aos recursos.

article.js

var mongoose = require('mongoose'),
Artigo = mongoose.model("Artigo"),
    ObjectId = mongoose.Types.ObjectId

exports.createArtigo = function(req, res, next) {
    var articleModel = new Artigo(req.body);
    articleModel.save(function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Erro ocorrido: " + err
            })
        } else {
            res.json({
                type: true,
                data: article
            })
        }
    })
}

exports.viewArtigo = function(req, res, next) {
    Artigo.findById(new ObjectId(req.params.id), function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Erro ocorrido: " + err
            })
        } else {
            if (article) {
                res.json({
                    type: true,
                    data: article
                })
            } else {
                res.json({
                    type: false,
                    data: "Artigo: " + req.params.id + " não encontrado"
                })
            }
        }
    })
}

exports.viewArtigo_v2 = function(req, res, next) {
    Artigo.findById(new ObjectId(req.params.id), function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Erro ocorrido: " + err
            })
        } else {
            if (article) {
                article.title = article.title + " v2"
                res.json({
                    type: true,
                    data: article
                })
            } else {
                res.json({
                    type: false,
                    data: "Artigo: " + req.params.id + " não encontrado"
                })
            }
        }
    })
}

exports.updateArtigo = function(req, res, next) {
    var updatedArtigoModel = new Artigo(req.body);
    Artigo.findByIdAndUpdate(new ObjectId(req.params.id), updatedArtigoModel, function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Erro ocorrido: " + err
            })
        } else {
            if (article) {
                res.json({
                    type: true,
                    data: article
                })
            } else {
                res.json({
                    type: false,
                    data: "Artigo: " + req.params.id + " não encontrado"
                })
            }
        }
    })
}

exports.deleteArtigo = function(req, res, next) {
    Artigo.findByIdAndRemove(new Object(req.params.id), function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Erro ocorrido: " + err
            })
        } else {
            res.json({
                type: true,
                data: "Artigo: " + req.params.id + " removido com sucesso"
            })
        }
    })
}

Uma explicação básica das operações CRUD em relação ao Mongoose pode ser visto logo abaixo:

createArtigo: A operação save simplesmente salva os dados recebidos no corpo da requisição, usando o modelo articleModel. Um novo objeto Artigo pode ser criado, enviando os dados do corpo da requisição para o modelo em questão, dessa forma var articleModel = new Artigo(req.body).
viewArtigo: Para vermos os detalhes do artigo, é preciso que tenhamos o ID de um artigo como parâmetro na URL. O método findOne usando o ID do parâmetro é mais que o suficiente para retornar os detalhes do artigo.
updateArtigo: A atualização de um Artigo é uma simples consulta e manipulação de dados em relação ao artigo retornado. Por fim, o artigo atualizado precisa ser salvo na base de dados, através do comando save.
deleteArtigo: O método findByIdAndRemove é a melhor forma de removermos um artigo a partir do ID de um artigo.

Os comandos do Mongoose mencionados acima são quase como métodos estáticos do objeto Artigo, o qual é uma referência a um esquema do Mongoose.

comment.js

var mongoose = require('mongoose'),
Comentários = mongoose.model("Comentarios"),
    Artigo = mongoose.model("Artigo"),
    ObjectId = mongoose.Types.ObjectId

exports.viewComentarios = function(req, res) {
    Artigo.findOne({"comments._id": new ObjectId(req.params.id)}, {"comments.$": 1}, function(err, comment) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Erro ocorrido: " + err
            })
        } else {
            if (comment) {
                res.json({
                    type: true,
                    data: new Comentarios(comment.comments[0])
                })
            } else {
                res.json({
                    type: false,
                    data: "Comentário: " + req.params.id + " não encontrado"
                })
            }
        }
    })
}

exports.updateComentarios = function(req, res, next) {
    var updatedComentariosModel = new Comentarios(req.body);
    console.log(updatedComentariosModel)
    Artigo.update(
        {"comments._id": new ObjectId(req.params.id)},
        {"$set": {"comments.$.text": updatedComentariosModel.text, "comments.$.author": updatedComentariosModel.author}},
        function(err) {
            if (err) {
                res.status(500);
                res.json({
                    type: false,
                    data: "Erro ocorrido: " + err
                })
            } else {
                res.json({
                    type: true,
                    data: "Comentário: " + req.params.id + " atualizado"
                })
            }
    })
}

exports.deleteComentarios = function(req, res, next) {
    Artigo.findOneAndUpdate({"comments._id": new ObjectId(req.params.id)},
        {"$pull": {"comments": {"_id": new ObjectId(req.params.id)}}},
        function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Erro ocorrido: " + err
            })
        } else {
            if (article) {
                res.json({
                    type: true,
                    data: article
                })
            } else {
                res.json({
                    type: false,
                    data: "Comentários: " + req.params.id + " não encontrado"
                })
            }
        }
    })
}

Ao realizar uma requisição a uma das URIs, a função declarada no controlador será executada. Cada função dentro dos arquivos de controladores pode usar os objetos req e res. O recurso comentário logo acima, é um sub-recurso de Artigo. Todas as operações de consultas são realizadas através do modelo Artigo para, então, encontrarmos o subdocumento e realizar as atualizações necessárias. Contudo, toda vez que tentamos visualizar um recurso do tipo Comentário, você verá algo, mesmo que não exista uma coleção no MongoDB.

Outras Sugestões de Design

Escolha recursos simples de entender para prover uso fácil aos clientes;
Não deixe a lógica do negócio ser implementada pelos clientes. Por exemplo, o recurso Artigo tem um campo chamado slug. Os clientes não precisam enviar esse detalhe pela API RESTful. A estratégia em relação ao slug deve ser administrada no lado da API RESTful para minimizar o acoplamento entre a API e os clientes. Os clientes só precisam enviar o título e você pode gerar o slug de acordo com as necessidades do negócio, no lado da API RESTful.
Implemente uma camada de autorização para suas APIs. Clientes não autorizados não podem acessar dados restritos pertencentes a outros usuários. Neste tutorial, não falamos sobre o recurso Usuário, mas você pode ler o artigo Autenticação com Tokens Usando AngularJS & NodeJS para mais informações em relação a autenticação de APIs.
URIs amigáveis ao invés de vetor de consulta. /articles/123 é bom, /articles?id=123 é ruim.
Não mantenha estados; sempre use entrada/saída instantâneas.
Use substantivos para seus recursos. Você poderá usar os métodos/verbos HTTP para operar sobre os recursos.

Finalmente, se você projetar uma API RESTful seguindo essas regras fundamentais, você sempre terá um sistema flexível, manutenível e compreensível.

Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!