Progettazione API: creazione di una risorsa in due fasi

Question

Progettazione API: creazione di una risorsa in due fasi

#1 da (1 voti)

3

Sto sviluppando un'API che consente ai consumatori di creare una risorsa. Ad esempio, una risorsa "utente" può un po ' essere creata tramite POST e questo payload (cercando di utilizzare JSON API , btw):

POST /users HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "users",
    "attributes": {
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

Dico un po ' creato perché la risorsa viene effettivamente creata su un sistema esterno (e la mia API funge da proxy).

Per completamente creare la risorsa, la mia API deve fare il secondo passo - e questo passaggio si basa su informazioni a cui la mia API non ha accesso. Il consumatore dell'API riceverà, in un secondo momento, queste informazioni aggiuntive (ad esempio tramite un SMS). L'utente dell'API deve quindi chiamare di nuovo la mia API con queste informazioni aggiuntive per completare il secondo passaggio della creazione della risorsa.

Come dovrebbe apparire questa chiamata secondaria alla mia API? Sarebbe comunque un POST a /users , giusto? Forse basta sostituire attributes con le informazioni aggiuntive (ad esempio "sms_key": "SHy562NSkd" )?

POST /users HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "users",
    "attributes": {
      "sms_key": "SHy562NSkd"
    }
  }
}

Si noti che l'API può eseguire completamente questo passaggio secondario senza alcuna conoscenza del primo passaggio, ma l'API ha un modo per sposare il secondo passo con il primo passaggio (potrebbe essere utile per restituire i risultati relativi alla risorsa creata).

api-design api rest

posta ProgrammerNewbie 02.07.2017 - 08:31

fonte

1 risposta

Leggi altre domande sui tag api-design api rest

Convalida del dominio accessibile dal livello di presentazione Utilizzo di un array come variabile membro in una classe

score 1 · Answer 1

Scusami anticipatamente per aver trascurato un fattore chiave in questa domanda. API JSON è una specifica.

In primo luogo, l'API JSON implementa HATEOAS che a mio parere facilita la risposta alla domanda.

Seguendo il tuo ultimo commento, ho controllato il sito web ufficiale e, come mi aspettavo, l'API JSON e io sono allineati con la soluzione che ti serve. Tuttavia, differiamo in alcuni punti.

Passaggio 1: Creazione di una nuova risorsa

Consenti agli utenti di scoprire la nuova risorsa. Questo è essenzialmente ciò che HATEOAS suggerisce. Se lo facciamo, i consumatori possono seguire il link e indirizzare ulteriori operazioni al nuovo URI.

Per brevità, tralascerò la richiesta e il corpo della risposta .

Dai un'occhiata all'esempio:

1.1. Richiesta

POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/and.api+json

1.2. Risposta

HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/vnd.api+json

Nota che /photos e /users sono equivalenti. Guarda le intestazioni di risposta. Come ho commentato nella mia risposta precedente, la risposta DOVREBBE contenere l'intestazione Location che contiene l'URL della nuova risorsa. In questo modo rendiamo disponibili nuove risorse dopo la sua creazione.

Particolare attenzione alla specifica, che afferma che, in base allo stato della risorsa sul lato server, dovremmo rispondere con uno o un altro codice.

Potresti essere interessato alle risposte 202 Accepted se la risorsa nell'API remota (quella che stai trasmettendo) non viene creata al momento della richiesta. Ad esempio, quando la risorsa remota viene creata in qualsiasi momento nel futuro. Consulta la terza documentazione API. È importante che tu sappia qual è lo stato della risorsa remota dopo la richiesta POST.

1.3. L'identificatore

Hai commentato che hai un modo per sposare entrambi i passaggi. Significa che hai un modo per identificare la risorsa remota nell'API remota. Belle. Devi rendere disponibili tali meccanismi. Forse con un ID posticipato o magari usando l'identificatore di risorse remote. Qualunque cosa tu scelga, la rendi disponibile al resto attraverso l'URI risultante ( /users/1 ).

2. Aggiornamento delle risorse

Ecco dove sono diverse le API JSON e I. L'API JSON sostiene le richieste PATCH . Non sono un fan di PATCH (probabilmente perché sono riluttante a inviare pezzi del mio modello di dati). Tuttavia, entrambi presuppongono che la risorsa esista già (passaggio 1).

Guarda l'esempio.

2.1. Richiesta

PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Come per creazione , il codice di stato della risposta dipenderà dallo stato della risorsa sul lato server. Dovrai decidere in ogni caso quale usare.

Riepilogo

Essenzialmente, la creazione della risorsa in due passaggi può essere tradotta in:

Passaggio 1: Crea (POST / utenti)
Passaggio 2: aggiornamento (PATCH / users / here_your_identifier)