Diseño de API RESTful con NodeJS y Restify

Spanish (Español) translation by Elías Nicolás (you can also view the original English article)

Final product image — What You'll Be Creating

La API RESTful consta de dos conceptos principales: Recurso y Representación. El recurso puede ser cualquier objeto asociado con datos, o identificado con un URI (más de un URI puede referirse al mismo recurso), y puede ser operado usando métodos HTTP. La representación es la forma en que muestra el recurso. En este tutorial, cubriremos algunos datos teóricos sobre el diseño RESTful API e implementaremos un ejemplo de API de aplicación de blog utilizando NodeJS.

Recurso

Elegir los recursos correctos para una API RESTful es una sección importante del diseño. En primer lugar, debe analizar el dominio de su negocio y luego decidir cuántos y qué tipo de recursos se utilizarán que sean relevantes para su negocio. Si está diseñando una API de blogging, probablemente use Article, User y Comment. Esos son los nombres de los recursos, y los datos asociados con eso son los recursos mismos:

{
    "title": "How to Design RESTful API",
    "content": "RESTful API design is a very important case in the software development world.",
    "author": "huseyinbabal",
    "tags": [
        "technology",
        "nodejs",
        "node-restify"
        ]
    "category": "NodeJS"
}

Verbos de recursos

Puede continuar con una operación de recursos después de haber decidido los recursos necesarios. La operación aquí se refiere a los métodos HTTP. Por ejemplo, para crear un artículo, puede hacer la siguiente solicitud:

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

{
  "title": "RESTful API Design with Restify",
  "slug": "restful-api-design-with-restify",
  "content": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  "author": "huseyinbabal"
}

De la misma manera, puede ver un artículo existente emitiendo la siguiente solicitud:

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

¿Qué hay de actualizar un artículo existente? Puedo escuchar que estás diciendo:

Puedo hacer otra solicitud de POST a / articles / update / 123456789012 con la carga.

Quizás sea preferible, pero el URI se está volviendo más complejo. Como dijimos anteriormente, las operaciones pueden referirse a métodos HTTP. Esto significa, indicar la operación de actualización en el método HTTP en lugar de poner eso en el URI. Por ejemplo:

PUT /articles/123456789012 HTTP/1.1
Host: localhost:3000
Content-Type: application/json
{
    "title": "Updated How to Design RESTful API",
    "content": "Updated RESTful API design is a very important case in the software development world.",
    "author": "huseyinbabal",
    "tags": [
        "technology",
        "nodejs",
        "restify",
        "one more tag"
        ]
    "category": "NodeJS"
}

Por cierto, en este ejemplo, verá etiquetas y campos de categoría. Esos no necesitan ser campos obligatorios. Puede dejarlos en blanco y configurarlos en el futuro.

En ocasiones, debe eliminar un artículo cuando esté desactualizado. En ese caso, puede usar una solicitud HTTP DELETE a /articles/123456789012.

Los métodos HTTP son conceptos estándar. Si los usa como una operación, tendrá URI simples, y este tipo de API simple lo ayudará a obtener consumidores satisfechos.

¿Qué sucede si quiere insertar un comentario en un artículo? Puede seleccionar el artículo y agregar un nuevo comentario al artículo seleccionado. Al usar esta declaración, puede usar la siguiente solicitud:

POST /articles/123456789012/comments HTTP/1.1
Host: localhost:3000
Content-Type: application/json
{
    "text": "Wow! this is a good tutorial",
    "author": "john doe"
}

La forma de recurso anterior se llama como un sub-recurso. Comment es un sub recurso de Article. La carga de Comment anterior se insertará en la base de datos como elemento secundario de Article. A veces, un URI diferente se refiere al mismo recurso. Por ejemplo, para ver un comentario específico, puede usar:

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

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

Versiones

En general, las características de API cambian frecuentemente para proporcionar nuevas características a los consumidores. En ese caso, pueden existir dos versiones de la misma API al mismo tiempo. Para separar esas dos características, puede usar el control de versiones. Hay dos formas de control de versiones

Versión en URI: puede proporcionar el número de versión en el URI. Por ejemplo, /v1.1/articles/123456789012.
Versión en encabezado: proporcione el número de versión en el encabezado y nunca cambie el URI. Por ejemplo:

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

En realidad, la versión solo cambia la representación del recurso, no el concepto del recurso. Por lo tanto, no necesita cambiar la estructura de URI. En v1.1, tal vez se agregó un nuevo campo a Article. Sin embargo, todavía devuelve un artículo. En la segunda opción, el URI sigue siendo simple y los consumidores no necesitan cambiar su URI en las implementaciones del lado del cliente.

Es importante diseñar una estrategia para situaciones en las que el consumidor no proporciona un número de versión. Puede generar un error cuando no se proporciona la versión, o puede devolver una respuesta utilizando la primera versión. Si usa la última versión estable como predeterminada, los consumidores pueden obtener muchos errores para sus implementaciones del lado del cliente.

Representación

La representación es la forma en que una API muestra el recurso. Cuando llamas a un punto final API, recibirás un recurso. Este recurso puede estar en cualquier formato como XML, JSON, etc. JSON es preferible si está diseñando una nueva API. Sin embargo, si está actualizando una API existente que solía devolver una respuesta XML, puede proporcionar otra versión para una respuesta JSON.

Esa es suficiente información teórica sobre el diseño RESTful API. Echemos un vistazo al uso de la vida real diseñando e implementando una API de blogs utilizando Restify.

Blogging REST API

Diseño

Para diseñar una API RESTful, tenemos que analizar el dominio comercial. Entonces podemos definir nuestros recursos. En una API de blogs, necesitamos:

Crear, actualizar, eliminar, ver Article
Crear un comentario para un Article específico, actualizar, eliminar, ver, Comment
Crear, actualizar, eliminar, ver User

En esta API, no cubriré cómo autenticar a un usuario para crear un artículo o comentario. Para la parte de autenticación, puede consultar la Autenticación basada en tokens con el tutorial AngularJS & NodeJS.

Nuestros nombres de recursos están listos. Las operaciones de recursos son simplemente CRUD. Puede consultar la siguiente tabla para obtener una muestra general de API.

Nombre del recurso	verbos HTTP	Metodos HTTP
Article	crear artículo actualizar artículo Eliminar artículo ver Artículo	POST /articles con carga PUT /articles/123 con carga ELIMINAR /articles/123 GET /article/123
Comment	crear comentario actualización Comentario Eliminar comentario ver comentario	POST /articles/123/comments con carga PUT /comments/123 con carga DELETE /comments/123 GET /comments/123
User	crear usuario actualizar usuario borrar usuario ver usuario	POST /users con carga útil PUT /users/123 con carga útil ELIMINAR /users/123 GET /users/123

Configuración del proyecto

En este proyecto usaremos NodeJS con Restify. Los recursos se guardarán en la base de datos MongoDB. Antes que nada, podemos definir recursos como modelos en Restify.

Article

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

var ArticleSchema = new Schema({
    title: String,
    slug: String,
    content: String,
    author: {
        type: String,
        ref: "User"
    }
});
mongoose.model('Article', ArticleSchema);

Comment

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

var CommentSchema = new Schema({
    text: String,
    article: {
        type: String,
        ref: "Article"
    },
    author: {
        type: String,
        ref: "User"
    }
});
mongoose.model('Comment', CommentSchema);

User

No habrá ninguna operación para el recurso de usuario. Supondremos que ya conocemos al usuario actual que podrá operar artículos o comentarios.

Puede preguntar de dónde viene este módulo mongoose. Es el marco ORM más popular para MongoDB escrito como un módulo NodeJS. Este módulo está incluido en el proyecto dentro de otro archivo de configuración.

Ahora podemos definir nuestros verbos HTTP para los recursos anteriores. Puedes ver lo siguiente:

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())

// Article Start
server.post("/articles", controllers.article.createArticle)
server.put("/articles/:id", controllers.article.updateArticle)
server.del("/articles/:id", controllers.article.deleteArticle)
server.get({path: "/articles/:id", version: "1.0.0"}, controllers.article.viewArticle)
server.get({path: "/articles/:id", version: "2.0.0"}, controllers.article.viewArticle_v2)
// Article End

// Comment Start
server.post("/comments", controllers.comment.createComment)
server.put("/comments/:id", controllers.comment.viewComment)
server.del("/comments/:id", controllers.comment.deleteComment)
server.get("/comments/:id", controllers.comment.viewComment)
// Comment End

var port = process.env.PORT || 3000;
server.listen(port, function (err) {
    if (err)
        console.error(err)
    else
        console.log('App is ready at : ' + port)
})

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

En este fragmento de código, primero se iteran los archivos del controlador que contienen los métodos del controlador y todos los controladores se inicializan para ejecutar una solicitud específica al URI. Después de eso, los URI para operaciones específicas se definen para las operaciones CRUD básicas. También hay control de versiones para una de las operaciones en Article.

Por ejemplo, si declara la versión como 2 en el encabezado Accept-Version, se ejecutará viewArticle_v2. viewArticle y viewArticle_v2 hacen el mismo trabajo, mostrando el recurso, pero muestran el recurso Artículo en un formato diferente, como se puede ver en el campo title a continuación. Finalmente, el servidor se inicia en un puerto específico y se aplican algunas comprobaciones de informes de errores. Podemos proceder con los métodos de controlador para las operaciones HTTP en los recursos.

article.js

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

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

exports.viewArticle = function(req, res, next) {
    Article.findById(new ObjectId(req.params.id), function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Error occured: " + err
            })
        } else {
            if (article) {
                res.json({
                    type: true,
                    data: article
                })
            } else {
                res.json({
                    type: false,
                    data: "Article: " + req.params.id + " not found"
                })
            }
        }
    })
}

exports.viewArticle_v2 = function(req, res, next) {
    Article.findById(new ObjectId(req.params.id), function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Error occured: " + err
            })
        } else {
            if (article) {
                article.title = article.title + " v2"
                res.json({
                    type: true,
                    data: article
                })
            } else {
                res.json({
                    type: false,
                    data: "Article: " + req.params.id + " not found"
                })
            }
        }
    })
}

exports.updateArticle = function(req, res, next) {
    var updatedArticleModel = new Article(req.body);
    Article.findByIdAndUpdate(new ObjectId(req.params.id), updatedArticleModel, function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Error occured: " + err
            })
        } else {
            if (article) {
                res.json({
                    type: true,
                    data: article
                })
            } else {
                res.json({
                    type: false,
                    data: "Article: " + req.params.id + " not found"
                })
            }
        }
    })
}

exports.deleteArticle = function(req, res, next) {
    Article.findByIdAndRemove(new Object(req.params.id), function(err, article) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Error occured: " + err
            })
        } else {
            res.json({
                type: true,
                data: "Article: " + req.params.id + " deleted successfully"
            })
        }
    })
}

Puede encontrar una explicación de las operaciones CRUD básicas en el lado Mongoose a continuación:

createArticle: esta es una operación simple save en articleModel enviada desde el cuerpo de la solicitud. Se puede crear un nuevo modelo pasando el cuerpo de la solicitud como un constructor a un modelo como var articleModel = new Article(req.body).
viewArticle: para ver los detalles del artículo, se necesita una ID de artículo en el parámetro de URL. findOne con un parámetro de ID es suficiente para devolver los detalles del artículo.
updateArticle: la actualización de artículo es una consulta de búsqueda simple y algo de manipulación de datos en el artículo devuelto. Finalmente, el modelo actualizado debe guardarse en la base de datos emitiendo un comando save.
deleteArticle: findByIdAndRemove es la mejor manera de eliminar un artículo proporcionando la ID del artículo.

Los comandos de Mangosta mencionados anteriormente son simplemente estáticos como método a través del objeto Artículo que también es una referencia del esquema de Mongoose.

comment.js

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

exports.viewComment = function(req, res) {
    Article.findOne({"comments._id": new ObjectId(req.params.id)}, {"comments.$": 1}, function(err, comment) {
        if (err) {
            res.status(500);
            res.json({
                type: false,
                data: "Error occured: " + err
            })
        } else {
            if (comment) {
                res.json({
                    type: true,
                    data: new Comment(comment.comments[0])
                })
            } else {
                res.json({
                    type: false,
                    data: "Comment: " + req.params.id + " not found"
                })
            }
        }
    })
}

exports.updateComment = function(req, res, next) {
    var updatedCommentModel = new Comment(req.body);
    console.log(updatedCommentModel)
    Article.update(
        {"comments._id": new ObjectId(req.params.id)},
        {"$set": {"comments.$.text": updatedCommentModel.text, "comments.$.author": updatedCommentModel.author}},
        function(err) {
            if (err) {
                res.status(500);
                res.json({
                    type: false,
                    data: "Error occured: " + err
                })
            } else {
                res.json({
                    type: true,
                    data: "Comment: " + req.params.id + " updated"
                })
            }
    })
}

exports.deleteComment = function(req, res, next) {
    Article.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: "Error occured: " + err
            })
        } else {
            if (article) {
                res.json({
                    type: true,
                    data: article
                })
            } else {
                res.json({
                    type: false,
                    data: "Comment: " + req.params.id + " not found"
                })
            }
        }
    })
}

Cuando realiza una solicitud a uno de los URI de recursos, se ejecutará la función relacionada indicada en el controlador. Cada función dentro de los archivos del controlador puede usar los objetos req y res. El recurso comment aquí es un sub recurso de Article. Todas las operaciones de consulta se realizan a través del modelo Article para encontrar un subdocumento y realizar la actualización necesaria. Sin embargo, cada vez que intente ver un recurso Comment, verá uno incluso si no hay una colección en MongoDB.

Otras sugerencias de diseño

Seleccione recursos fáciles de entender para facilitar el uso a los consumidores.
Deje que los consumidores implementen la lógica de negocios. Por ejemplo, el recurso Article tiene un campo llamado slug. Los consumidores no necesitan enviar este detalle a la API REST. Esta estrategia de babosas debe administrarse en el lado REST API para reducir el acoplamiento entre la API y los consumidores. Los consumidores solo necesitan enviar los detalles del título, y usted puede generar el slug de acuerdo con las necesidades de su negocio en el lado REST API.
Implemente una capa de autorización para sus puntos finales API. Los consumidores no autorizados pueden acceder a datos restringidos que pertenecen a otro usuario. En este tutorial, no cubrimos el recurso de usuario, pero puede consultar Autenticación basada en tokens con AngularJS y NodeJS para obtener más información sobre las autenticaciones API.
URI de usuario en lugar de cadena de consulta. /articles/123 (Bueno), /articles?id=123 (Malo).
No guardes el estado; siempre use entrada / salida instantánea.
Usa el sustantivo para tus recursos. Puede usar métodos HTTP para operar en recursos.

Finalmente, si diseña una API RESTful siguiendo estas reglas fundamentales, siempre tendrá un sistema flexible, fácil de mantener y fácil de entender.