4 visitas

JSON-LD: El lenguaje oculto que potencia nuestras APIs 🚀

Cuando hablamos de APIs modernas, muchas veces nos enfocamos en REST, GraphQL o en cómo estructurar endpoints… pero hay un aliado silencioso que hace que nuestras respuestas sean más ricas, comprensibles y conectadas: **JSON-LD**. En este post vamos a ver **cómo nos ayuda JSON-LD en el desarrollo de APIs**, cómo se implementa en **API Platform (Symfony)**, algunos **tips para optimizarlo**, y por qué **no siempre es la solución mágica**.

📌 ¿Qué es JSON-LD?

JSON-LD (JavaScript Object Notation for Linked Data) es un formato de serialización de datos que sigue las reglas de Linked Data, pensado para que las máquinas puedan entender mejor la información que enviamos. En palabras simples: le da contexto a los datos.

Por ejemplo, si tenés:

{
  "nombre": "Juan Pérez",
  "email": "juan@example.com"
}

Para una máquina, eso son solo strings. Pero con JSON-LD podés decir explícitamente que nombre es un schema:Person y que email es un schema:email.

🛠 Implementación en API Platform (Symfony)

API Platform es prácticamente el paraíso del JSON-LD porque lo soporta out of the box. Cuando configurás tus entidades como recursos (@ApiResource), API Platform genera automáticamente endpoints con serialización JSON-LD.

Ejemplo con Symfony 7 + API Platform:

<?php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ApiResource(
    formats: ['jsonld' => ['application/ld+json']],
    normalizationContext: ['groups' => ['empleado:read']],
    denormalizationContext: ['groups' => ['empleado:write']]
)]
class Empleado
{
    #[ORM\Id, ORM\GeneratedValue, ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private string $nombre;

    #[ORM\Column(length: 255, unique: true)]
    private string $email;

    // Getters y setters...
}

Con esta configuración, si accedés a /api/empleados/1, obtendrás algo así:

{
  "@context": "/api/contexts/Empleado",
  "@id": "/api/empleados/1",
  "@type": "Empleado",
  "id": 1,
  "nombre": "Juan Pérez",
  "email": "juan@example.com"
}

💡 Tips para optimizar JSON-LD en API Platform

Tip	Descripción	Beneficio
Usar `normalizationContext` con `groups`	Solo exponer campos necesarios	Reduce payload y mejora seguridad
Personalizar `@context`	Definir tus propios contextos y vocabularios	Hace la API más semántica
Cachear el contexto	El endpoint `/api/contexts/...` puede cachearse	Aumenta performance
Deshabilitar si no se usa	Si tu cliente no lo necesita, desactivalo	Menos overhead en serialización

Ejemplo para personalizar el contexto:

#[ApiResource(
    normalizationContext: [
        'groups' => ['empleado:read'],
        'jsonld_context' => [
            '@vocab' => 'https://schema.org/',
            'nombre' => 'givenName',
            'email' => 'email'
        ]
    ]
)]

Esto hará que tu JSON-LD sea más semántico y compatible con vocabularios estándar como schema.org.

✅ Pros y ❌ Contras de JSON-LD en APIs

Pros	Contras
Facilita la interoperabilidad entre sistemas	Payload más grande
Ayuda a que motores de búsqueda y crawlers entiendan mejor la data	Curva de aprendizaje si no conocés Linked Data
API Platform lo soporta automáticamente	Puede ser innecesario si no se consume de forma semántica
Ideal para integraciones con IA y conocimiento semántico	Más complejidad en customización de contextos

📌 Conclusiones

JSON-LD no es solo un formato más de salida. Es un puente semántico entre tu API y el mundo de datos interconectados. Si trabajás con API Platform en Symfony, su implementación es prácticamente automática, y con algunos ajustes podés optimizarlo tanto para humanos como para máquinas.

Eso sí: no uses JSON-LD solo por moda. Evaluá si tu ecosistema lo necesita, y si sí, aprovechá su potencial para darle más significado a tus datos.

📖 Glosario

JSON-LD: Formato JSON para representar datos enlazados (Linked Data).
Contexto (@context): Define el significado de las propiedades en el JSON-LD.
API Platform: Framework sobre Symfony para construir APIs REST y GraphQL de forma rápida.
Vocabulario: Conjunto de términos definidos (como schema.org) para dar significado a los datos.
Payload: El contenido de una respuesta HTTP.