json - tutorial - ventajas de hateoas

¿Cómo deberían implementarse los enlaces al estilo HATEOAS para las colecciones RESTful JSON?

Question

Para mantener las cosas simples y evitar el nombre de colisiones, he estado agrupando enlaces en mis recursos de registro como este ...

{
    id: 211,
    first_name: ''John'',
    last_name: ''Lock'',
    _links: [
        { rel: ''self'', href: ''htttp://example.com/people/211'' }
    ]
}

Sin embargo, no puedo encontrar la forma de implementar enlaces en colecciones. He pasado mucho tiempo buscando en la red ejemplos y otras cosas que no sean la HAL no tan delgada. No puedo conciliar mi problema.

[
    {id:1,first_name:.....},
    {id:2,first_name:.....},
    {id:3,first_name:.....}, 
    "_links": "Cant put a key value pair here because its an-array" 
]

Lo que significa que tengo que envolver la matriz en un objeto contenedor.

[
    people: [ {id:1,first_name:.....} ],
    links: [ { rel:parent, href:.... ]
]

Pero es diferente al recurso singular, así que voy a hacer que el registro se comporte como la colección y lo envuelva en un contenedor ...

{
    person: {
        id: 211,
        first_name: ''John'',
        last_name: ''Lock'',
        _links: 
    },
    links:[
        { rel: ''self'', href: ''htttp://example.com/people/211'' }
    ] 
}

En la superficie esto parece una solución bastante clara. El JSON resultante tiene un nivel más profundo pero HATEOAS se ha implementado, así que todo está bien, ¿verdad? De ningún modo. La verdadera punzada viene cuando vuelvo a la colección. Ahora que el único recurso se ha envuelto en un contenedor para ser coherente con la colección, la colección ahora debe cambiarse para reflejar los cambios. Y aquí es donde se pone feo. Muy feo. Ahora la colección se ve así ...

{
    "people": [
        {
            "person": {
                ....
            },
            "links" : [
                {
                    "rel": "self",
                    "href": "http://example.com/people/1"
                }
            ]
        },
        {
            "person": {
                ....
            },
            "links" : [
                {
                    "rel": "self",
                    "href": "http://example.com/people/2"
                }
            ]
        }
    ],
    "links" : [
        {
            "rel": "self",
            "href": "http://example.com/people"
        }
    ]
}

¿Existe una solución más simple para implementar HATEOAS para las colecciones? ¿O debería despedirme de HATEOAS por forzarme a complicar demasiado la estructura de datos?

Answer 1

Puede intentar ver la especificación de objeto Restful . Que chicos creen una API concreta. Como no me gusta toda la idea, hay muchas soluciones prácticas que puedes obtener de ellas.

Answer 2

En primer lugar, no creo que las API que tienen puntos finales que devuelven colecciones (matrices JSON) sean realmente RESTful. Sin embargo, la mayoría de las API de "REST" doblan las reglas aquí.

Recientemente desarrollé una API REST para el feed NextBus XML llamado restbus que devuelve colecciones desde algunos puntos finales mientras usa enlaces de hipertexto de estilo HATEOAS. Aquí hay una muestra de la estructura que utilicé:

{
  // ... SF-Muni resource from restbus API ...

  _links: {
    self: {
      href: "http://localhost:3535/agencies/sf-muni",
      type: "application/json",
      rel: "self",
      rt: "agency",
      title: "Transit agency ''sf-muni''."
    },
    to: [
      {
        href: "http://localhost:3535/agencies/sf-muni/routes",
        type: "application/json",
        rel: "describedby",
        rt: "route",
        title: "A collection of routes for transit agency ''sf-muni''."
      },
      {
        href: "http://localhost:3535/agencies/sf-muni/vehicles",
        type: "application/json",
        rel: "describedby",
        rt: "vehicle",
        title: "A collection of vehicles for transit agency ''sf-muni''."
      }
    ],
    from: [
      {
        href: "http://localhost:3535/agencies",
        type: "application/json",
        rel: "bookmark",
        rt: "agency",
        title: "A collection of transit agencies. This is the API root!"
      }
    ]
  }

}

No intenta seguir ninguna de las populares estrategias de enlace JSON (o sus tipos de medios asociados) como HAL et al . porque no parecen estar en la Pista de estándares IETF (todavía). En cambio, los atributos de destino del objeto de enlace y los valores de relación de enlace cumplen con las especificaciones de enlace web RFC 5988 tanto como sea posible.

Puede ver más detalles sobre la estructura de enlace de hipertexto de restbus .

Answer 3

Por favor, no descarte HAL tan rápido solo porque se ve un poco hinchado (en su forma JSON, es bastante mínimo).

HAL es para JSON lo que HTML es para texto sin formato.

Agrega hipervínculos. Necesita hipervínculos y un formato de representación comúnmente entendido (como HAL o Collection + JSON) para REST. ¡También necesita HATEOAS para DESCANSO, sin HATEOAS no es RESTO! HATEOAS requiere hipervínculos, por supuesto.

En tu caso, estás intentando construir un recurso de colección. La relación registrada por IANA para eso es "artículo" (con relación inversa "colección"). Aquí está la representación en HAL para una colección People:

{
    "_links": {
        "self": { "href": "http://example.com/people" },
        "item": [
            { "href": "http://example.com/people/1", "title": "John Smith" },
            { "href": "http://example.com/people/2", "title": "Jane Smith" }
        ]
    },
    "_embedded": {
        "http://example.com/rels#person": [
            {
                "first_name": "John",
                "last_name": "Smith",
                "_links": {
                    "self": { "href": "http://example.com/people/1" },
                    "http://example.com/rels#spouse": { "href": "http://example.com/people/2" }
                }
            },
            {
                "first_name": "Jane",
                "last_name": "Smith",
                "_links": {
                    "self": { "href": "http://example.com/people/2" },
                    "http://example.com/rels#spouse": { "href": "http://example.com/people/1" }
                }
            }
        ]
    }
}

Nota:

• Los datos principales para esta colección provienen de _links.item[] . Estos son los artículos en la colección. Los datos completos (o al menos algunos adicionales) para cada elemento están disponibles en la matriz _embedded . Si el cliente necesita estos datos adicionales, debe encontrarlos buscando a través de _embedded[n]._links.self.href para cada n . Esta es una restricción de diseño de HAL. Otros formatos de representación hipermedia tienen restricciones similares (aunque quizás vayan en la otra dirección).

• He agregado un valor de title para cada miembro de la matriz de item . Esto puede aparecer entre las etiquetas de anclaje de apertura y cierre si se procesa en HTML, o como el texto de un elemento de menú en el cliente, sin necesidad de un procesamiento posterior de la representación por parte del cliente.

• No hay parámetros de ID. Todas las referencias a otros recursos están expuestas como hipervínculos. Un cliente no debería tener que "construir" una URL pegando una ID en una URL en un lugar predefinido. Esto constituye información fuera de banda que inhibe los cambios independientes en el cliente y el servidor.

• Todos sus hipervínculos deben ser absolutos, ya que las URL relativas pueden causar problemas. Todas sus relaciones deben aparecer en esa página de IANA o usar un URI para definirlas. Idealmente, ese URI debe ser una URL HTTP sin referencia con documentación sobre la relación en el otro extremo.

Answer 4

Parece que la vinculación JSON aún no es un problema resuelto. Hay varios contendientes:

• HAL
• API JSON
• JSON-LD
• Colección + JSON
• SIRENA

Referencias

• https://sookocheff.com/post/api/on-choosing-a-hypermedia-format/
• http://jsonapi.org/