¿Cómo modelar una API RESTful con herencia?

Me gustaría ir para / animales que devuelven una lista de perros y peces y lo que sea:

<animals>
  <animal type="dog">
    <name>Fido</name>
    <fur-color>White</fur-color>
  </animal>
  <animal type="fish">
    <name>Wanda</name>
    <water-type>Salt</water-type>
  </animal>
</animals>

Debería ser fácil implementar un ejemplo JSON similar.

Los clientes siempre pueden confiar en que el elemento "name" esté allí (un atributo común). Pero dependiendo del atributo "type" habrá otros elementos como parte de la representación animal.

No hay nada inherentemente RESTful o intranquilo en devolver tal lista-REST no prescribe ningún formato específico para representación de datos. Todo lo que dice es que los datos deben tener alguna representación y el formato para esa representación se identifica por el tipo de medio (que en HTTP es el encabezado Content-Type).

Piense en sus casos de uso: ¿necesita mostrar una lista de animales mixtos? Bueno, entonces devuelve una lista de datos de animales mezclados. ¿Necesita una lista de perros? Bueno, haz una lista.

Si lo haces /animales?tipo = perro o / perros es irrelevante con respecto al DESCANSO que no prescribir cualquier formato de URL-que se deja como un detalle de implementación fuera del alcance de REST. REST solo indica que los recursos deben tener identificadores, sin importar el formato.

Debe agregar algunos enlaces de hyper media para acercarse a una API RESTful. Por ejemplo, añadiendo referencias a los detalles del animal:

<animals>
  <animal type="dog" href="/animals/123">
    <name>Fido</name>
    <fur-color>White</fur-color>
  </animal>
  <animal type="fish" href="/animals/321">
    <name>Wanda</name>
    <water-type>Salt</water-type>
  </animal>
</animals>

Mediante la adición de hipervínculos multimedia se reduce el acoplamiento cliente / servidor - en el caso anterior se toma la carga de la construcción de URL lejos del cliente y dejar que el servidor decidir cómo construir URLs (que por definición es la única autoridad de).

Esta pregunta se puede responder mejor con el apoyo de una mejora reciente introducida en la última versión de OpenAPI.

Ha sido posible combinar esquemas usando palabras clave como oneOf, allOf, anyOf y obtener una carga útil de mensaje validada desde el esquema JSON v1.0.

Https://spacetelescope.github.io/understanding-json-schema/reference/combining.html

Sin embargo, en OpenAPI (anteriormente Swagger), la composición de esquemas ha sido mejorada por las palabras clave discriminador (v2.0+) y oneOf (v3.0+) para realmente apoyar el polimorfismo.

Https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaComposition

Su herencia podría ser modelada usando una combinación de oneOf (para elegir uno de los subtipos) y allOf (para combinar el tipo y uno de sus subtipos). A continuación se muestra una definición de ejemplo para el método POST.

paths:
  /animals:
  post:
   requestBody:
    content:
      application/json:
        schema:
          oneOf:
            - $ref: '#/components/schemas/Dog
            - $ref: '#/components/schemas/Cat
            - $ref: '#/components/schemas/Fish
          discriminator:
            propertyName: animal_type
   responses:
     '201':
       description: Created
components:
  schemas:
    Animal:
      type: object
      required:
        - animal_type
        - name
      properties:
        animal_type:
          type: string
        name:
          type: string
      discriminator:
        property_name: animal_type
    Dog:
      allOf:
        - $ref: "#/components/schemas/Animal"
        - type: object
        - properties:
          playsFetch
            type: string
    Cat:
      allOf:
        - $ref: "#/components/schemas/Animal"
        - type: object
        - properties:
          likesToPurr
            type: string
    Fish:
      allOf:
        - $ref: "#/components/schemas/Animal"
        - type: object
        - properties:
          water-type
            type: string

Pero ahora la relación entre perros y gatos está perdida.

De hecho, pero tenga en cuenta que URI simplemente nunca refleja las relaciones entre objetos.

Sé que esta es una vieja pregunta, pero estoy interesado en investigar más problemas sobre un modelo de herencia relajante

Siempre puedo decir que un perro es un animal y una gallina también, pero la gallina hace huevos mientras que el perro es un mamífero, por lo que no puede.]}

OBTENER animales/: animalID / huevos

No es consistente porque indica que todos los subtipos de animales pueden tener huevos (como consecuencia de la sustitución de Liskov). Habría una alternativa si todos los mamíferos responden con ' 0 ' a esto solicitud, pero ¿qué pasa si también habilito un método POST? ¿Debo tener miedo de que mañana haya huevos de perro en mis crepes?

La única manera de manejar estos escenarios es proporcionar un 'super-recurso' que agregue todos los sub-recursos compartidos entre todos los 'recursos derivados' posibles y luego una especialización para cada recurso derivado que lo necesite, al igual que cuando bajamos un objeto a oop

GET / animals/: animalID / sons GET / hens/: animalID / huevos POST / gallinas/: animales / huevos

El inconveniente, aquí, es que alguien podría pasar una identificación de perro para hacer referencia a una instancia de la colección de gallinas, pero el perro no es una gallina, por lo que no sería incorrecto si la respuesta fue 404 o 400 con un mensaje de razón

¿Me equivoco?