Sinatra para Ruby: qué es y tu primera aplicación
¿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
- Copia la API de tareas y sus tests. Añade un test para
DELETE /tareas/1que espere un204y compruebe que la tarea ya no está. Comprueba que falla. - Escribe la ruta con
delete "/tareas/:id" do … endhasta que el test pase. ¿Qué debería devolver si la tarea no existe? - Quita el
rescue JSON::ParserErrory pasa los tests: el del JSON roto acaba en error, no en failure. Después arranca el servidor, envía{tituloconcurly 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:
bindescucha enlocalhosten desarrollo y en0.0.0.0en el resto;host_authorizationadmite en desarrollo.localhost,.testy cualquier dirección IP, y bloquea el resto con un403;raise_errors, activado por defecto en el entornotest;halt,status,beforeycontent_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 peticionescurldesde 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) yruby: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 peticionescurldesde 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 elrescue, el test acaba con elJSON::ParserErrory el servidor responde500, y que una listapermitted_hostspropia deja fueralocalhostsi no se incluye.