Progettazione dello schema JSON per risposta variabile

Question

Progettazione dello schema JSON per risposta variabile

#1 da (1 voti)
#2 da (0 voti)

0

Sto redigendo uno schema JSON per un'API. Una delle risposte mira a mostrare tutti gli aggiornamenti alle diverse proprietà di una determinata entità. Il numero di aggiornamenti può variare da una risposta all'altra. Ad esempio, può essere che i valori di property_a e property_d cambino in una risposta e quelli di property_a , property_b e property_c nel successivo.

Voglio progettare uno schema che sia al contempo amichevole con l'interpretazione umana e l'esecuzione programmatica.

Un esempio concreto di tale entità può essere la prenotazione di un appuntamento. Ogni appuntamento può consistere in un luogo, una data, un'ora e un elenco di partecipanti e tutti possono cambiare dopo la creazione di un appuntamento. Ora vogliamo avere un endpoint API che restituisca qualsiasi aggiornamento a un appuntamento esistente. La risposta contiene solo le proprietà aggiornate.

Fin qui ho trovato qualcosa di simile:

{
    "event": "update",
    "appointment_id": 123,
    "updated_properties": ["place", "time"],
    "place": "some new location",
    "time": "some new time"
}

In sostanza, questo schema indica quali proprietà sono aggiornate e restituisce semplicemente queste proprietà solo con i loro nuovi valori.

È un design sensato? Qualsiasi schema alternativo per miglioramenti?

api-design api json

posta skyork 19.04.2015 - 01:35

fonte

2 risposte

Leggi altre domande sui tag api-design api json

Miglior flusso di lavoro per un team di sviluppo web che lavori su una grande quantità di progetti contemporaneamente? [duplicare] La sintassi regex in .net 3.5 è la stessa della sintassi regex nell'ultima versione di .net framework in c #?

score 1 · Answer 1

Potresti prendere in considerazione la possibilità di modificare il valore per updated_properties in un oggetto anziché in un array e di elencare il nuovo valore direttamente nell'elenco delle proprietà aggiornate. Ciò ridurrà la dimensione complessiva del messaggio.

{
    "event": "update",
    "appointment_id": 123,
    "updated_properties: {
        "place": "some new location",
        "time": "some new time"
    },
    "added_properties": {
        "attendees": [{"name": "Some Name", "role": "organizer"}]
    }
}

La risposta che stai descrivendo sembra provenire da una richiesta POST o PUT, quindi puoi anche semplicemente elencare le proprietà aggiornate / aggiunte nell'oggetto, affermando nella documentazione che tutte le proprietà dell'oggetto non vengono restituite, solo le proprietà aggiornate . L'utente può eseguire una richiesta GET per ottenere tutte le proprietà se necessario.

{
    "event": "update",
    "appointment_id": 123,
    "place": "some new location",
    "time": "some new time",
    "attendees": [{"name": "Some Name", "role": "organizer"}]
}

Entrambi gli approcci sarebbero accettabili.

score 0 · Answer 2

Potresti utilizzare la patch JSON per rappresentare le modifiche a un'entità. Suggerirei di separare lo stato corrente dalla sua "cronologia delle modifiche"

Ci sono librerie per linguaggi di programmazione comuni che ti aiutano a generare le patch

Un esempio:

La risorsa:

GET /appointments/123
Last-Modified: Sun, 07 Aug 2016 07:00:00 GMT

{
    "appointment_id: 123,
    "place": "some new location",
    "time": "some new time"
}

Endpoint per le modifiche:

GET /appointments/123/history?limit=1

[
  {
    date: '2016-08-07T07:00:00Z',
    change: [
      { "op": "replace", "path": "/time", "value": "som new time" },
      { "op": "add", "path": "/place", "value": "some new locatin" }
    ]
  }
]