Come installare correttamente la documentazione per i servizi di riluttanza in un'architettura di micro-servizi (HAL, ALPS)

Question

Ho letto molto su come configurare correttamente i microservizi e mi sono ritrovato con alcuni concetti più recenti tra cui: HAL, ALPS e il browser HAL. Ho storicamente documentato le cose sfruttando l'interfaccia utente di Swagger, tuttavia, sto arrivando a capire che URL centric non è il modo giusto e dovrei organizzare la documentazione su risorse e collegamenti, che è ciò per cui sono le tecnologie più recenti. Ho alcune lacune di conoscenza intorno a questi nuovi concetti, quindi volevo avere una comprensione corretta di come queste tecnologie lavorassero insieme, così come apprendo su ciascuna di esse posso inserirle nel puzzle.

mia comprensione attuale è:

HAL - è un formato supplementare sulla parte superiore del JSON che vi permetterà di navigare attraverso la vostra API tramite link.

ALPI - Si tratta di un formato supplementare sulla parte superiore del JSON che può farmi fornire descrizioni basate inglese per aiutare a descrivere le mie risorse

HAL Browser - sostituzione Swagger interfaccia utente per risorse e Link documentazione centric. Funziona con HAL e ALPS insieme?

La mia attuale comprensione di queste tecnologie sarebbe accurata o carente in alcune aree? Inoltre, per quanto riguarda l'implementazione, non riesco a comprendere appieno come interagiscono ALPS e HAL. Ero a conoscenza di un formato hal + json e di un alps + json, ma non ho visto un hal + alps + json.

L'ultima area che vorrei chiarire è come dovrei esporre queste risorse. In genere mi sono sempre concentrato su messaggi JSON molto snelli che inviano il formato hal + json attorno al previsto o dovrei ospitare questi endpoint su un altro URL appositamente per la documentazione simile al browser swagger/HAL?

Answer 1

Buddy! è un'inferno di informazioni che stai cercando di percepire qui. Lasciami provare a spiegare nei passaggi.

La documentazione centrica indica le transizioni tra i servizi e Sì, dovrebbe essere chiamata come condivisione semantica delle informazioni (o comprensione come tipi di dati) sul web.

Fase: 1 protocolli (http) utilizzati per i servizi con tipi di dati e metadati tipi di dati standard potrebbe essere qualsiasi forma di ipermedia cioè HTML, XML, JSON, HAL ecc Per esempio JSON mostrato di seguito, che è un documento di root con collegamenti. Sia 'todos' che 'profile' sono solo collegamenti ipermediali che sono basati su HAL e HAL aumenta solo le tue attuali API.

{ "_links" : { 
    "todos" : { 
     "href" : "http://localhost:8080/todos" 
    }, 
    "profile" : { 
     "href" : "http://localhost:8080/alps" 
    } 
    } 
} 

Si noti che il suo solo legami con possibile collegamento risorsa che può puntare alla semantica di risorse. L'obiettivo principale di HAL è solo collegare risorse/modelli tramite link, proprietà e/o incorporamento. Gli accessi illustrati sopra sono principalmente collegamenti a tipi di dati condivisi a livello di protocollo.

Fase: 2 ALPS sono le affordance livello di applicazione che significano al precedente JSON so cosa la Todo è ma come interagiscono con esso? Per interagire con Todo, è necessario avere transizioni di stato a livello di applicazione. Considera di seguito il JSON "todo" che naviga dal link e mostra parole chiave extra dettagliate come "descrittori" e "Tipo" (SEMANTICO, SICURO, UNSAFE, ecc.).

Le proprietà 'id' diventano identificatori di rappresentazione. Questi sono impostati o Regole per applicare lo stato e le transizioni ALPS indipendenti.

{ "version" : "1.0", 
    "descriptors" : [ { 
    "id" : "todo-representation", 
    "descriptors" : [ { 
     "name" : "description", 
     "doc" : { 
     "value" : "Details about the TODO item", 
     "format" : "TEXT" 
     }, 
     "type" : "SEMANTIC" 
    }, { 
     "name" : "title", 
     "doc" : { 
     "value" : "Title for the TODO item", 
     "format" : "TEXT" 
     }, 
     "type" : "SEMANTIC" 
    }, { 
     "name" : "id", 
     "type" : "SEMANTIC" 
    } ] 
    }, { 
    "id" : "get-todos", 
    "name" : "todos", 
    "type" : "SAFE", 
    "rt" : "#todo-representation" 
    }, { 
    "id" : "create-todos", 
    "name" : "todos", 
    "type" : "UNSAFE", 
    "rt" : "#todo-representation" 
    }, { 
    "id" : "delete-todo", 
    "name" : "todo", 
    "type" : "IDEMPOTENT", 
    "rt" : "#todo-representation" 
    }, { 
    "id" : "patch-todo", 
    "name" : "todo", 
    "type" : "UNSAFE", 
    "rt" : "#todo-representation" 
    }, { 
    "id" : "get-todo", 
    "name" : "todo", 
    "type" : "SAFE", 
    "rt" : "#todo-representation" 
    } ] 
} 

Alcuni link valgono per controllare in dettaglio slides about ALPS e Rest Example. Spero che questo ti abbia aiutato a capire.

Answer 2

Ho un URL di documentazione swagger api in ogni micro servizio. Es: http://myservice1domain:8080/swagger-ui.html. Non ho usato ALPS. Inoltre, non penso che devi o puoi esporre in modo specifico solo il tipo di HAL perché sono vincolanti con i dati di risposta. In ogni caso HAL espone all'utente in spavalderia come corpo di richiesta campione e con risposta json right