Ajustes en el contrato de actualización (PUT vs PATCH) del TP2C 2025

Detectamos una inconsistencia en la especificación OpenAPI del enunciado original para actualizar canciones (PUT /songs/{id}). El contrato permitía cuerpos parciales (ninguna propiedad required), lo que contradice la semántica estándar de HTTP: PUT reemplaza la representación completa del recurso y es idempotente; no es safe. (RFC Editor, IETF Datatracker)

📌 ¿Qué cambiamos?

• Antes: UpdateSongRequest no exigía campos obligatorios, habilitando un “PUT parcial”.

  components:
    schemas:
      UpdateSongRequest:
        type: object
        properties:
          title: { type: string }
          artist: { type: string }

• Ahora: PUT /songs/{id} vuelve a ser reemplazo completo e idempotente. Por eso, UpdateSongRequest exige ambos campos.

  components:
    schemas:
      UpdateSongRequest:
        type: object
        required:
            - title
            - artist
        properties:
          title: { type: string }
          artist: { type: string }

Nota OpenAPI: requestBody.required: true solo marca que hay cuerpo; los campos obligatorios se definen en el Schema mediante required: [...]. (Swagger, OpenAPI Initiative Publications)

Ejemplo de uso (PUT = reemplazo completo)

{
  "title": "Bohemian Rhapsody",
  "artist": "Queen"
}

🔍 Recordatorio rápido de semántica HTTP (safe / idempotent)

• GET → safe e idempotent.
• POST → no safe, no idempotent por defecto.
• PUT → no safe, sí idempotent (reemplaza por completo).
• PATCH → no safe, no idempotent por defecto (puede diseñarse idempotente). (RFC Editor, MDN Web Docs, IETF Datatracker)

Safe: métodos cuya semántica es solo lectura y no piden cambios de estado en el servidor.

No safe: métodos que sí pueden modificar el estado o producir efectos secundarios.

Idempotente: en HTTP, repetir la misma solicitud varias veces deja el recurso/servidor en el mismo estado que si se hiciera una sola vez (aunque el código/respuesta pueda variar).

• “A request method is considered ‘idempotent’ if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request.” RFC 9110 §9.2.2 — https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods (RFC Editor)

• “It knows that repeating the request will have the same intended effect, even if the original request succeeded, though the response might differ.” RFC 9110 §9.2.2 — https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods (RFC Editor)

¿Qué significa este cambio para vos?

• Si tu implementación hacía que PUT aceptara parciales, ajustala para que requiera title y artist (reemplazo completo).
• Si ya tenías PUT como reemplazo total, no necesitás cambios.
• El formato de respuestas no cambia.

Fuentes

• RFC 9110 — HTTP Semantics (definiciones de safe e idempotent; PUT/DELETE idempotentes): https://www.rfc-editor.org/rfc/rfc9110.html (RFC Editor)
• MDN — Métodos HTTP (tabla de safe/idempotent): https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods (MDN Web Docs)
• RFC 5789 — Método PATCH (no es seguro ni idempotente por defecto): https://datatracker.ietf.org/doc/rfc5789/ (IETF Datatracker)
• OpenAPI 3.0 — requestBody.required (cuerpo requerido): https://swagger.io/docs/specification/v3_0/describing-request-body/describing-request-body/ (Swagger)
• OpenAPI 3.0.3 — Especificación oficial: https://spec.openapis.org/oas/v3.0.3.html (OpenAPI Initiative Publications)