restful - JSON Hypermedia Api con formularios y enlaces.

restful net

Question

Estoy en las primeras etapas de la planificación de una API REST, y me gustaría que se adhiera a la restricción HATEOAS de REST. Pero también me gustaría proporcionar un formato JSON. Entonces, mi pregunta es si hay convenciones para representar enlaces y formularios en JSON.

He encontrado ejemplos de enlaces, y parece que esta es una forma bastante común de representar enlaces:

"links": [ 
{"rel": "self", "href":"http://example.org/entity/1"},
{"rel": "friends", "href":"http://example.org/entity/1/friends"}] 

Por otro lado, representar formas no es algo de lo que haya visto mucho. Estaba pensando que tal vez alguien se había sentado y había pensado algo en este sentido, pero consideró todas las advertencias:

"forms" : [
{"rel" : "new client", "action" : "/clients", "method": "post", 
"fields" : ["name":"string", "zipcode":"int", "signedup":"date", "state": ["Alabama",...]...]}]

La inspiración para esto proviene de mirar este video, donde Jon Moore sugiere que JSON no es un buen formato para una API de hipermedia:

http://oredev.org/2010/sessions/hypermedia-apis

Una charla muy buena por cierto!

¡Toda la entrada es apreciada!

Answer 1

Actualmente no hay un formato JSON de propósito general con especificación pública con formularios, que yo sepa. Usted es libre de definir uno si lo necesita y publicar las especificaciones. Como preferencia personal, recomiendo basarse en HAL.

Si decide escribir uno propio, cree una lista de correo e invite a otros a participar. Si no lo hace, correría el peligro de adaptarlo demasiado para satisfacer sus propias necesidades y, accidentalmente, pasar por alto algún requisito que le impida ser ampliamente aplicable.

Answer 2

Echa un vistazo a Colección + JSON, HAL y / o Sirena.

Answer 3

El estándar de esquema JSON (en particular, los "hipersquemas") definitivamente lo permite. Hace referencia a un esquema JSON (Hiper) (utilizando encabezados HTTP) y el esquema define reglas sobre cómo interpretar sus datos como hipertexto.

La información para construir sus enlaces puede estar en cualquier lugar. El hipervema documenta cómo ensamblar los URI de enlace a partir de los datos (puede ser una plantilla), y también especifican el método HTTP, el tipo de codificación, etc.

Para obtener la funcionalidad del formulario: puede especificar un esquema completo para los datos que se enviarán junto con la solicitud. Propiedades requeridas / opcionales, restricciones de longitud de matriz, lo que sea.

A modo de demostración, aquí hay parte de un tutorial para una biblioteca de JavaScript que entiende los hiperdemas y puede presentar un formulario apropiado para los enlaces: jsonary.com .

Answer 4

He estado trabajando en una API, utilizando JSON Hyper Schema. Puede navegar por Aroun e incluso registrarse, iniciar sesión y realizar algunas acciones. Échale un vistazo, aquí: http://api.psprt.com

[EDITAR] Vea mis últimas cosas aquí: www.passportedu.com https://github.com/bpanahij/HypermediaServer https://github.com/bpanahij/client-schema.json

También abro el código de la API: https://github.com/bpanahij/passportedu_schema

Siéntase libre de echar un vistazo, pedir prestado y comentar.

JSON Hyper Schema (ver también JSON-Schema ) tiene una forma de especificar formularios, a través del miembro de propiedades:

{
"id": "/api/v1",
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PassportEDU API",
"name": "PassportEDU API",
"type": "object",
"description": "Bringing global students together with global schools.",
"links": [
   {
      "title": "Log In",
      "rel": "authenticate",
      "href": "/api/v1/authenticate",
      "method": "POST",
      "properties": {
        "username": {
          "title": "Your username",
          "description": "Your email address or username",
          "type": "string"
        },
        "password": {
          "title": "Your password",
          "description": "Your password",
          "type": "password"
        }
      },
      "required": ["username", "password"]
   }
   ]
}

Answer 5

He investigado este tema por un tiempo, pero no estoy seguro de qué soluciones posibles utiliza ppl y cuáles no. Solo hay algunos ejemplos disponibles ... Así que necesitaré una revisión por parte de expertos ... (Mis ejemplos estarán principalmente en HAL + JSON).

1.)

Tengo la sensación de que las relaciones de enlace deben ser GET solamente, porque en HTML son para incluir cosas como hojas de estilo. Supongo que otras personas tenían el mismo sentimiento, porque hay una forma de edit-form y una forma de create-form por las relaciones de enlace de la IANA.

• Por lo tanto, la primera solución posible para desreferenciar vínculos con relaciones de formulario y así descargar las descripciones de formulario para las operaciones de escritura. Estas descripciones de formularios pueden contener fragmentos HTML o un esquema que podemos usar para generar los formularios. Por ejemplo

  Solo por mencionar que puede usar el mismo enfoque enviando los mismos enlaces en el encabezado y enviando JSON sin formato como cuerpo.

  {
      "_links": {
          "edit-form": {
              "href": "http://example.com/users/1?form=edit",
              "type": "text/html",
              "title": "Edit user"
          }
      }
  }

Entonces, ¿qué pasa si las relaciones de enlace no son sólo para fines de lectura?

2.)

Luego podemos usar las características integradas de HAL:

• Si enviamos datos, podemos usar el type para describir el cuerpo de la solicitud en lugar del cuerpo de la respuesta. De c. en este caso no debería haber un cuerpo de respuesta, o esta solución será confusa.

      {
          "_links": {
              "curies": [
                  {
                      "name": "my",
                      "href": "http://example.com/rels/{rel}",
                      "templated": true
                  }
              ],
              "my:edit": {
                  "href": "http://example.com/users/1",
                  "type": "application/vnd.example.user+json",
                  "title": "Edit user"
              }
          }
      }

  Entonces, en este caso, el cliente sabrá que my:edit significa que este es un formulario de edición, y al marcar el tipo MIME sabrá qué tipo de formulario mostrar.

• Una solución alternativa para utilizar la relación de enlace personalizada para el mismo propósito:

      {
          "_links": {
              "curies": [
                  {
                      "name": "my",
                      "href": "http://example.com/rels/{rel}",
                      "templated": true
                  }
              ],
              "my:edit-user": {
                  "href": "http://example.com/users/1",
                  "type": "application/json",
                  "title": "Edit user"
              }
          }
      }

  Por lo tanto, al buscar los documentos http://example.com/rels/edit-user podemos encontrar una descripción sobre cómo crear un formulario para editar usuarios y así poder respaldar la relación my:edit-user link en nuestro cliente. Los documentos pueden contener opcionalmente un formulario HTML o algún esquema, o un documento RDF utilizando un vocabulario de descripción de formulario, etc.

• Podemos seguir el mismo enfoque por la propiedad de profile de los enlaces. Por ejemplo:

      {
          "_links": {
              "curies": [
                  {
                      "name": "my",
                      "href": "http://example.com/rels/{rel}",
                      "templated": true
                  }
              ],
              "my:edit": {
                  "href": "http://example.com/users/1",
                  "type": "application/json",
                  "title": "Edit user",
                  "profile": "http://example.com/profiles/user"
              }
          }
      }

  Entonces, aquí, la relación de enlace significa que este es un formulario de edición y el profile describe cómo generar el formulario bajo la URL de http://example.com/profiles/user .

3.)

O podemos extender HAL usando propiedades personalizadas.

• Por ejemplo, dougrain-forms hace esto:

      {
          "_forms": {
              "edit": {
                  "href": "http://example.com/users/1",
                  "headers": {
                      "content-type": "application/json"
                  },
                  "title": "Edit user",
                  "method": "PUT",
                  "schema": {
                      "required": [
                          "name"
                      ],
                      "type": "object",
                      "properties": {
                          "name": {
                              "type": "string"
                          }
                      },
                      "title": "user properties"
                  }
              }
          }
      }

• Pero puede utilizar cualquier enfoque alternativo siempre que no tengamos un estándar sobre HAL y sobre los formularios de HAL, por ejemplo, preferiría usar un esquema de mangosta como una solución:

      {
          "name": "John",
          "_links": {
              "curies": [
                  {
                      "name": "my",
                      "href": "http://example.com/rels/{rel}",
                      "templated": true
                  }
              ],
              "my:edit": {
                  "href": "http://example.com/users/1",
                  "type": "application/json",
                  "title": "Edit user",
                  "method": "PUT",
                  "_embedded": {
                      "schema": {
                          "name": "String"
                      }
                  }
              }
          }
      }

4.)

No use relaciones de enlace y formatos JSON simples como HAL, use RDF con uno o más vocabulario en su lugar. Es más difícil usar RDF, pero es una solución de grano fino para desacoplar a los clientes de los servicios REST, mientras que HAL es solo una solución de grano grueso ...

• Por ejemplo, JSON-LD con Hydra y un vocabulario personalizado:

  {
      "@context": [
          "http://www.w3.org/ns/hydra/core",
          "https://example.com/docs#"
      ],
      "@id": "https://example.com/users/1",
      "name": "John",
      "operation": {
          "@type": "ReplaceResourceOperation",
          "title": "Edit user",
          "method": "PUT",
          "expects": {
              "@id": "https://example.com/docs#User",
              "supportedProperty": {
                  "@type": "SupportedProperty",
                  "title": "name",
                  "property": "https://example.com/docs#User.name",
                  "range": "http://www.w3.org/2001/XMLSchema#string",
                  "required": true
              }
          }
      }
  }