convenzione API per "variabili" lato server

Question

convenzione API per "variabili" lato server

#1 da (8 voti)
#2 da (2 voti)
#3 da (1 voti)

2

Sto guardando uno scenario API in cui hai un'entità, come una telefonata, che puoi interrompere una volta e iniziare una volta. Stavo pensando di modellare questo come qualcosa del tipo:

{
  start_time: null | date,
  end_time: null | date
}

Tuttavia, non voglio che il client sia effettivamente in grado di impostare liberamente questi campi. Piuttosto, voglio che siano in grado di inviare una richiesta a questa risorsa per avviarla, per cui il server imposta l'ora corrente in base al proprio orologio, e quindi per inviare una richiesta alla fine, per cui il server fa la stessa cosa per il campo end_time.

Che mi ha portato a chiedermi, esiste una convenzione API che specifica le variabili che possono essere utilizzate in richiesta? Ad esempio, potrei prevedere una API che specifica che una variabile denominata "$ now" rappresenta l'ora corrente in base all'API. Con questo sistema, se al 2017-03-06T01: 55: 42 + 00: 00 (dall'orologio del server) invii ...

PUT /call/1/

{
  start_time: "$now",
  end_time: null
}

... vedresti, in una successiva richiesta di ottenere:

GET /call/1/

{
  start_time: "2017-03-06T01:55:42+00:00",
  end_time: null
}

Qualcuno sa di una convenzione per specificare cose come questa - in particolare, per delineare quali variabili di questo tipo sono disponibili per il cliente e cosa significano? E 'un buon modo per fare le cose in una risorsa (non dirò RESTful, perché non hypermedia)?

api-design api rest

posta samfrances 03.08.2017 - 09:53

fonte

3 risposte

Leggi altre domande sui tag api-design api rest

Utilizzo di SRP con Object Thinking Frequenza dell'accesso getter

score 8 · Answer 1

C'è una ragione per inviare gli elementi start_time|end_time dal client se il server sta gestendo i tempi? Probabilmente farei qualcosa di simile a quanto segue, sebbene il design dell'API abbia molta preferenza -

POST /call
    {caller_id: value, ...}

Invia una richiesta contenente eventuali metadati di chiamata (come i numeri src / dst, ecc.) Ciò userebbe l'ora corrente all'inizio della chiamata e restituirà un riferimento / ID di chiamata scelto dal server.

PUT /call/{ref}
    {ended: true}

Invia un aggiornamento con un elemento ended: true per indicare la fine della chiamata. Il server può quindi applicare l'ora corrente al suo campo end_time .

Si basa sull'API che gestisce le chiamate in tempo reale senza alcuna possibilità per il client di specificare l'ora di inizio e di fine della chiamata. (Ad esempio, il client invia una richiesta all'avvio della chiamata e un'altra alla fine).

score 2 · Answer 2

Altre risposte a questo post forniscono alternative ragionevoli al mantenimento dei riferimenti di valore nella tua API. Illustrano anche la semplice risposta alla tua domanda:

No, non esiste una convenzione standard per specificare i riferimenti di valore in JSON.

Tutto ciò che esiste è un'idea di qualcuno su come risolvere un problema come il tuo. Alcune idee potrebbero funzionare meglio di altre.

Senza alcuni metadati incorporati nella tua API (ad esempio, WSDL o qualcosa che WCF può creare per te), il tuo unico meccanismo per trasmettere i dettagli della soluzione al tuo problema è documentarlo tu stesso, che potresti (o forse no) ) incorporare nella tua API.

Ma no, non esiste una convenzione generalmente accettata per riferimenti di valore o per documentarli in modo standard.

score 1 · Answer 3

Does anyone know of a convention for specifying things like this - specifically, for outlining which variables of this sort are available to the client and what they mean?

Indipendentemente dalle intenzioni sottostanti a questa domanda e dagli usi di queste variabili, considera la possibilità di trasformare queste variabili in risorse. ¹

GET /env/variables HTTP 1.1    
...

HTTP 200 Ok
...

{             
  "now":{
    "description":"Server's current date and time",
    "value":"2017-03-06T01:55:42+00:00",
    "time-zone":"UTC",
    "reference":"$now",
    "type": "Date"
   },
...
}

In questo modo, permettiamo ai clienti di essere a conoscenza di loro. Tuttavia, come digerire le variabili su entrambi -client e server-side dipende da te.

Torna alla domanda dell'OP 'e in base al suo esempio, come @USD Matt ha commentato, se sul lato server gestisce i timmings della chiamata, non è necessario che i client sappiano quali variabili entrano in gioco sul lato server e non c'è bisogno né di dire al server quali variabili usare.

Altrimenti, non ci sarebbe alcuna differenza tra consentire input arbitrari e consentire variabili specifiche come input. Il cliente sceglierebbe comunque il valore per tempo di inizio .

Nota : considera che potrebbero esserci 3 diversi tempi di avvio . L'ora di inizio del server, l'ora di inizio del server e l'ora di inizio per chi si trova dall'altro lato del filo.

^{1: La rappresentazione sopra è solo per illustrazione. Sentiti libero di implementare quello che meglio soddisfa i tuoi scopi.}