Nivel inicial9 min de lectura · Publicado el

Sinatra para Ruby: qué es y tu primera aplicación

Sinatra para Ruby: en app.rb, get "/" do "¡Hola, mundo!" end responde en el navegador; Rails necesita decenas de carpetas. Una web en un solo ficherorubentejera.com app.rbget "/" do "¡Hola, mundo!"endlocalhost:4567¡Hola, mundo!Rails: decenas de carpetas
Con Sinatra, tres líneas en un solo fichero ya responden «¡Hola, mundo!» en localhost:4567. Rails trae decenas de carpetas; Sinatra no decide por ti: base de datos, plantillas o usuarios los añades tú.

¿Qué es Sinatra, el framework de Ruby?

  • Es un framework para desarrollar aplicaciones web con el lenguaje de programación Ruby.
  • Lo diseñó y desarrolló Blake Mizerany en California, según su propio fichero de autores. Hoy lo mantiene un equipo de cinco personas.
  • Es más sencillo de aprender que Ruby on Rails.
  • Su web oficial es sinatrarb.com y el código está en GitHub.

Su propia documentación lo define como un DSL, un pequeño lenguaje hecho a medida para una tarea: aquí, decir «cuando alguien pida esta dirección, responde esto».

Rails te da una aplicación completa, con decenas de carpetas; Sinatra, un solo fichero: arrancas al momento, pero lo que necesites además (base de datos, plantillas, usuarios) lo traes tú.

Versión actual 4.2.1 (10 de octubre de 2025)
Licencia MIT
Documentación Un único README largo en inglés, en GitHub
Se apoya en Rack, la interfaz común entre aplicaciones web de Ruby y servidores

Tu primera aplicación

1. Instala las gemas

gem install sinatra rackup puma

La documentación oficial pide las tres: sinatra, rackup (que arranca la aplicación) y un servidor web como puma.

2. Escribe la aplicación

Crea un fichero app.rb:

require "sinatra"

get "/" do
  "¡Hola, mundo!"
end

get "/hola/:nombre" do
  "Hola, #{params[:nombre]}"
end

Cada bloque es una ruta: el método HTTP (get), la dirección ("/") y lo que se responde. :nombre es una parte variable de la dirección, que recoges con params[:nombre].

3. Arráncala

ruby app.rb

Abre http://localhost:4567 en el navegador o prueba con curl:

curl localhost:4567/hola/Ana
# Hola, Ana

Si cambias el código, para el servidor con Ctrl + C y vuelve a arrancarlo: Sinatra no recarga los cambios solo. El README propone herramientas como rerun si quieres que se reinicie automáticamente.

4. Pruébala con un test

La documentación oficial recomienda Rack::Test para probar una aplicación Sinatra sin arrancar el servidor. Instala gem install rack-test minitest y crea app_test.rb junto a app.rb:

ENV["APP_ENV"] = "test"
require_relative "app"
require "minitest/autorun"
require "rack/test"

class AppTest < Minitest::Test
  include Rack::Test::Methods

  def app = Sinatra::Application

  def test_saluda_por_nombre
    get "/hola/Ana"
    assert_equal "Hola, Ana", last_response.body
  end
end
ruby app_test.rb
# 1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

Sinatra solo arranca el servidor cuando ejecutas directamente app.rb; aquí ejecutas el test, así que no se levanta nada, y APP_ENV=test activa su entorno de pruebas. Como cada ruta es un bloque pequeño, es un buen terreno para practicar el ciclo de TDD: escribe primero el test de la ruta y después el bloque que lo hace pasar.

Una API pequeña con JSON

Un uso muy habitual de Sinatra es una API: un servicio que recibe y devuelve datos en JSON en lugar de páginas. Esta guarda tareas en memoria y ya usa lo esencial: rutas get y post, un filtro before que se ejecuta antes de cada ruta, códigos de estado con status y halt, que corta la petición y responde en el acto:

require "sinatra"
require "json"

TAREAS = []

before do
  content_type :json
end

get "/tareas" do
  TAREAS.to_json
end

post "/tareas" do
  begin
    datos = JSON.parse(request.body.read)
  rescue JSON::ParserError
    halt 400, { error: "JSON no válido" }.to_json
  end

  titulo = datos["titulo"].to_s.strip
  halt 422, { error: "falta el título" }.to_json if titulo.empty?

  tarea = { id: TAREAS.size + 1, titulo: titulo }
  TAREAS << tarea
  status 201
  tarea.to_json
end

get "/tareas/:id" do
  tarea = TAREAS.find { |t| t[:id] == params[:id].to_i }
  halt 404, { error: "no existe" }.to_json unless tarea
  tarea.to_json
end

Guárdalo como tareas.rb, arráncalo con ruby tareas.rb y, desde otra terminal, crea una tarea y pide la lista:

curl -X POST localhost:4567/tareas -H 'Content-Type: application/json' -d '{"titulo": "Comprar pan"}'
curl localhost:4567/tareas
{"id":1,"titulo":"Comprar pan"}
[{"id":1,"titulo":"Comprar pan"}]

Los códigos de estado le dicen al cliente qué ha pasado sin que tenga que leer el mensaje: 201 (creado), 400 (la petición está mal escrita), 404 (no existe) y 422 (se entiende, pero los datos no valen). Las tareas viven en memoria: al parar el servidor se pierden. Para guardarlas, Sinatra no trae nada; eliges tú la gema de base de datos.

Probar la API

Los tests de la API siguen el mismo patrón que el de antes, con un setup que vacía la lista para que cada test empiece de cero:

ENV["APP_ENV"] = "test"
require_relative "tareas"
require "minitest/autorun"
require "rack/test"

class TareasTest < Minitest::Test
  include Rack::Test::Methods

  def app = Sinatra::Application

  def setup = TAREAS.clear

  def crear(cuerpo) = post("/tareas", cuerpo, "CONTENT_TYPE" => "application/json")

  def test_crea_una_tarea
    crear({ titulo: "Comprar pan" }.to_json)

    assert_equal 201, last_response.status
    assert_equal({ "id" => 1, "titulo" => "Comprar pan" }, JSON.parse(last_response.body))
  end

  def test_rechaza_una_tarea_sin_titulo
    crear({ titulo: "  " }.to_json)

    assert_equal 422, last_response.status
    assert_equal "falta el título", JSON.parse(last_response.body)["error"]
  end

  def test_rechaza_un_json_mal_escrito
    crear("{titulo")

    assert_equal 400, last_response.status
  end

  def test_una_tarea_que_no_existe_da_404
    get "/tareas/99"

    assert_equal 404, last_response.status
  end
end
ruby tareas_test.rb
4 runs, 6 assertions, 0 failures, 0 errors, 0 skips

Con Ruby 3.4 verás además el aviso literal string will be frozen in the future, que apunta a un fichero de Rack. Sale porque Rack modifica el texto "{titulo" que le pasa el test. No cambia el resultado, y desaparece si escribes +"{titulo", que crea una copia modificable. Por qué pasa esto se explica en Símbolos en Ruby.

Fíjate en que los tests prueban justo los casos que más se olvidan: el título vacío, el JSON roto y la tarea que no existe. Sin el rescue JSON::ParserError, en el test saltaría el propio JSON::ParserError (en el entorno de pruebas Sinatra deja pasar las excepciones para que las veas), y con el servidor arrancado el cliente recibiría un 500, el código de «error del servidor».

Errores frecuentes

1. Instalar solo sinatra. Para arrancar necesita también rackup y un servidor web como puma. Si faltan, lo dice al arrancar:

ruby app.rb
Sinatra could not start, the required gems weren't found!

Add them to your bundle with:

    bundle add rackup puma

or install them with:

    gem install rackup puma

2. Pedir una ruta que no existe. Sinatra responde con un 404 y una página que dice Sinatra doesn’t know this ditty («Sinatra no conoce esta canción»), con el código que tendrías que escribir para crearla. Si te sale con una ruta que crees que existe, revisa el método (get frente a post) y la barra final: /tareas y /tareas/ son rutas distintas.

3. No poder entrar desde otro equipo o desde fuera de Docker. En desarrollo, Sinatra solo escucha en el propio equipo:

* Listening on http://127.0.0.1:4567
* Listening on http://[::1]:4567

Desde otro equipo, o desde tu navegador si la aplicación corre en un contenedor, la conexión falla. Arranca con -o 0.0.0.0 para que escuche en todas las interfaces:

ruby app.rb -o 0.0.0.0

4. Host not permitted. Aun escuchando en todas las interfaces, en desarrollo Sinatra solo acepta peticiones dirigidas a localhost, a nombres acabados en .localhost o .test y a direcciones IP. Con otro nombre, por ejemplo uno que has puesto en tu fichero hosts, responde con un 403 (la IP es la del contenedor de la prueba; usa la de tu equipo):

curl -H 'Host: mi-app.local' http://172.17.0.11:4567/tareas
Host not permitted

Es una protección contra el DNS rebinding, un ataque que engaña al navegador para que hable con tu servidor local. Si necesitas otro nombre, dalo en la opción host_authorization con permitted_hosts, como explica el README. Ojo: esa lista sustituye a la de por defecto, así que incluye también localhost si lo sigues usando.

5. Esperar que los cambios se vean solos. Como se ve en el paso 3, Sinatra no recarga el código; si no quieres reiniciarlo a mano, usa un recargador como rerun.

Sinatra o Ruby on Rails

Sinatra Ruby on Rails
Tamaño mínimo Un fichero Una aplicación con decenas de carpetas
Base de datos No trae; añades la gema que quieras Active Record incluido
Generadores No bin/rails generate para modelos, controladores…
Cuándo encaja APIs pequeñas, prototipos, servicios sencillos Aplicaciones completas con muchas pantallas y modelos

Si tu proyecto va a crecer, Rails te ahorra decisiones. Si quieres entender cómo funciona una web por dentro o montar algo pequeño en minutos, Sinatra es un buen punto de partida. Para dar el salto, mira cómo crear y arrancar un proyecto en Ruby on Rails.

Lo que conviene saber

  • La documentación está en inglés y es un único README muy largo. Usa el índice del principio para saltar a cada sección.
  • No decide por ti: base de datos, estructura de carpetas o autenticación los eliges tú. Es una ventaja en proyectos pequeños y un riesgo en los grandes, donde cada equipo acaba montando su propia estructura.
  • Estilo clásico y modular: los ejemplos de este artículo usan el estilo clásico (rutas sueltas en el fichero). Para aplicaciones más grandes, el README explica el estilo modular, con una clase que hereda de Sinatra::Base.

Cuándo no usar Sinatra

Sinatra encaja cuando la aplicación cabe en la cabeza: unas pocas rutas, un servicio que hace una cosa, un prototipo, o aprender cómo funciona una web sin magia. Deja de encajar cuando necesitas a la vez:

  • Muchos modelos con relaciones entre ellos (usuarios, pedidos, productos, facturas). Tendrás que elegir y conectar la base de datos, las migraciones y las validaciones; Rails las trae ya integradas.
  • Usuarios, sesiones y permisos. Se puede hacer con gemas, pero cada pieza es una decisión y una responsabilidad de seguridad que tomas tú.
  • Un equipo que crece. Sin convenciones, cada persona organiza el código a su manera. Rails, con su estructura fija, hace que cualquiera que lo conozca sepa dónde buscar.

Si vas a acabar montando a mano media Rails, empieza con Rails.

Alternativas actuales

  • Roda: también minimalista, organiza las rutas en forma de árbol. Versión 3.109.0.
  • Hanami: un framework completo, con más estructura que Sinatra, que se presenta como pensado para aplicaciones mantenibles. Versión 3.0.2.
  • Ruby on Rails: la opción completa. Versión 8.1.4.1.

Ejercicio de cinco minutos

  1. Copia la API de tareas y sus tests. Añade un test para DELETE /tareas/1 que espere un 204 y compruebe que la tarea ya no está. Comprueba que falla.
  2. Escribe la ruta con delete "/tareas/:id" do … end hasta que el test pase. ¿Qué debería devolver si la tarea no existe?
  3. Quita el rescue JSON::ParserError y pasa los tests: el del JSON roto acaba en error, no en failure. Después arranca el servidor, envía {titulo con curl y mira qué código de estado recibes.

Fuentes

Comprobado en noviembre de 2026:

  • README de Sinatra: instalación, primer ejemplo, recarga de código y sección de tests con Rack::Test.
  • AUTHORS.md: autoría y equipo actual.
  • RubyGems: versión 4.2.1, fecha de publicación y licencia MIT. Versiones de Roda, Hanami y Rails, también en RubyGems.
  • README de Sinatra, configuración: bind escucha en localhost en desarrollo y en 0.0.0.0 en el resto; host_authorization admite en desarrollo .localhost, .test y cualquier dirección IP, y bloquea el resto con un 403; raise_errors, activado por defecto en el entorno test; halt, status, before y content_type.
  • La aplicación y el test del artículo original se han ejecutado en Docker con la imagen ruby:3.4 (Ruby 3.4.12), sinatra 4.2.1, rackup 2.3.1, puma 8.0.2, rack-test 2.3.0 y minitest 6.1.0, con peticiones curl desde el propio contenedor.
  • La API de tareas, sus tests y los errores frecuentes se han ejecutado el 11 de noviembre de 2026 en Docker con las imágenes ruby:3.4 (Ruby 3.4.12) y ruby:4.0 (Ruby 4.0.9), con sinatra 4.2.1 (la última versión estable en RubyGems ese día), rackup 2.3.1, puma 8.0.2, rack 3.2.8 y rack-test 2.3.0, y peticiones curl desde el propio contenedor. La salida es la misma en las dos versiones salvo el aviso de Ruby 3.4 que se explica en el texto. También se ha comprobado que, sin el rescue, el test acaba con el JSON::ParserError y el servidor responde 500, y que una lista permitted_hosts propia deja fuera localhost si no se incluye.