Come implementare correttamente l'API REST di archiviazione key = value

Naviga le tue risposte
5

Sono nuovo all'API REST, quindi ho deciso di familiarizzarlo progettando una piccola API di servizi Web. Ho scritto il suo design e vorrei che lo esaminassi. Mi sento come se avessi commesso alcuni errori nel progettarlo e nel comprendere i concetti REST, che cerco di affrontare con domande sul mio design alla fine. Per la maggior parte non sono sicuro del mio utilizzo degli URL per l'API.

Il servizio Web che cerco di progettare fornisce un modo per memorizzare coppie chiave = valore, cioè recuperare il valore conoscendo la sua chiave, aggiornare il valore di una chiave esistente ed eliminare una chiave esistente. L'intero insieme di azioni CRUD!

Ecco cosa mi è venuto in mente.

Versioning

Poiché la mia API potrebbe evolversi, voglio una nozione di versioni API, quindi ho 

GET api.example.com/supported-versions

Che restituisce un elenco JSON di numeri interi che denotano le versioni API supportate.

L'API sarà disponibile a api.example.com/{VERSION}/ endpoint, ad es. api.example.com/1/ per la prima versione.

Chiave = memoria valori 

GET api.exmaple.com/1/keys/{KEY}

Consente a un utente di ottenere un valore associato a una chiave KEY . Il server risponde con un codice di stato (200, 404, ecc.) E un valore di testo in caso di successo, entrambi codificati in JSON. 

POST and PUT api.exmaple.com/1/keys/{KEY}?value={VALUE}

Consente a un utente di creare / aggiornare il valore associato alla chiave KEY . Il server restituisce un codice di stato (200, 404, ecc.). VALUE è una stringa di testo. 

DELETE api.exmaple.com/1/keys/{KEY}

Consente a un utente di eliminare una coppia chiave = valore con la chiave KEY . Il server che cancellerà la coppia chiave = valore e restituirà un codice di stato (200, 404, ecc.).

Immaginiamo che ci sia un setup di autenticazione OAuth2, che è usato per i metodi sopra POST / PUT / DELETE (ma non GET chiunque può ottenere, non hai bisogno di autenticazione per quello), quindi c'è un modo identificare un utente in modo univoco e tenere traccia di quali coppie chiave = valore appartengono a quale utente.

Ora desidero che un utente autenticato sia in grado di ottenere un elenco di tutte le chiavi che hanno, in modo che non debbano memorizzare queste informazioni sul lato client per inviare successivamente una richiesta DELETE o PUT. 

GET api.exmaple.com/1/keys?page={PAGE}

Ciò consente a un utente di ottenere un elenco di tutte le chiavi esistenti che hanno creato. PAGE è un parametro facoltativo. L'utente può aumentare il conteggio delle pagine fino a quando l'utente non riceve un codice di stato di errore. Restituisce un elenco a pagine di tutte le chiavi esistenti che un utente ha creato e anche un codice di stato (200, 404, ecc.).

C'è qualcosa di sbagliato in questa API?

La prima GET / POST / PUT / DELETE dalla sezione Chiave = valore di archiviazione deve essere su /keys/ o /values/ ?

Va bene che l'ultimo "GET", quello che restituisce tutte le chiavi che un utente ha, è anche /keys/ ?

    
posta Waffle Lord 03.01.2016 - 05:03
fonte

2 risposte

6

La soluzione è OK, ad eccezione di alcune cose:

  1. Le API REST di Versioning a livello di risorsa non sono generalmente una buona pratica, sebbene non necessariamente una visione di consenso. Vedi qui per alcuni commenti e link a ulteriori discussioni.

  2. Alla tua seconda domanda, potresti probabilmente discutere in ogni caso se /keys/{id}/ o /values/{id}/ sia corretto, ma il mio istinto sarebbe di usare keys poiché è il "genitore" della tupla , o userei un nome completamente diverso come /data/ o /elements/ , o qualunque cosa siano queste cose in realtà rappresentano.

  3. Probabilmente avrei diversi metodi GET per l'intero dizionario chiave-valore, ad es. /keys/{id} /, e una risorsa separata per quelli per un particolare utente, ad es. /users/{id}/keys/{keyId} .

Infine, non è fantastico (sebbene possibile) utilizzare le stringhe di query con i metodi POST / PUT / DELETE. È una stringa query , dopo tutto. Invece, potresti usare POST /data/ e inserire la coppia chiave-valore come dati JSON nel corpo della richiesta. Vedi questa domanda pure.

    
risposta data 03.01.2016 - 05:37
fonte
1

Quando il servizio REST restituisce un elenco di risorse, come le chiavi dell'utente o le versioni disponibili, restituisce (json) le strutture che contengono URL a tali risorse. Google per "dati collegati" per vedere i vantaggi di questo approccio.

es. la richiesta: 

HTTP> GET /Data/Version=1/User=Kasper/My_keys

Ne risulterebbe la risposta: 

200

{ keys: 
   [ 
      { name: "SO_account",
        link: "http://api.example.com/Data/Version=1/keys/SO_Account
      },
      { name: "Facebook_account";
        link: "http://api.example.com/Data/Version=1/keys/Facebook_account"
      }
   ]
}
    
risposta data 06.01.2016 - 15:27
fonte

Leggi altre domande sui tag

Progettare intorno a una costanza poco profonda con l'ereditarietà Il pattern di Repository Pattern e Active Record è compatibile?