Qual è la necessità di "rilevabilità" in un'API REST quando i client non sono abbastanza avanzati per utilizzarla comunque?

I vari discorsi che ho visto e le esercitazioni che ho scannerizzato su REST sembrano sottolineare qualcosa chiamato "rilevabilità". Per mia comprensione limitata, il termine sembra significare che un cliente dovrebbe essere in grado di andare http://URLe ottenere automaticamente un elenco di cose che può fare.

Quello che ho difficoltà a capire è che i "client software" non sono esseri umani. Sono solo programmi che non hanno le conoscenze intuitive per capire cosa fare esattamente con i collegamenti forniti. Solo le persone possono visitare un sito Web e dare un senso al testo e ai collegamenti presentati e agire su di esso.

Allora, qual è il punto di rilevabilità, quando il codice client che accede a tali URL rilevabili non può effettivamente fare nulla con esso, a meno che lo sviluppatore umano del client non provi effettivamente con le risorse presentate? Sembra esattamente la stessa cosa che definisce l'insieme delle funzioni disponibili in un manuale di documentazione, da una direzione diversa e che coinvolge effettivamente più lavoro per lo sviluppatore. Perché questo secondo approccio di pre-definizione di ciò che può essere fatto in un documento esterno alle risorse REST effettive, è considerato inferiore?

La necessità di rilevabilità potrebbe non essere pertinente, ma i collegamenti che consentono la rilevabilità servono a più scopi. Il più importante di questi, a mio avviso, è che fornire URI completi nelle risposte al cliente significa che nessun cliente dovrà mai "comporre" un URI. Ciò significa che nessun cliente avrà mai bisogno di conoscenza su come sono strutturati gli URI. E ciò a sua volta consente agli sviluppatori di server di modificare lo schema URI ogni volta che si adatta a loro in quanto non devono considerare i client più vecchi che fanno ancora affidamento su un vecchio modo di strutturare gli URI.

I "client" potrebbero non essere sufficientemente avanzati per utilizzarli, ma gli utenti dei client possono farlo. Dopo tutto, un client può essere qualcosa di semplice come un browser web. La rilevabilità si basa sul consentire alle persone di apprendere e utilizzare l'API .

Ad esempio, Jenkins (il server CI) ha un'interfaccia simile a REST. Vai a qualsiasi pagina, inserisci l'URL con "/ api" e otterrai una pagina che descrive tutto ciò che puoi fare. Rende l'apprendimento dell'API banale. Ad esempio, http://ci.jruby.org ti porta al server jenkins per jruby e http://ci.jruby.org/api ti porta all'API per quella pagina specifica.

Ho avuto il piacere di lavorare con un'API che aveva una documentazione molto, molto difficile da capire.

Una volta che sono riuscito a ottenere una risposta effettiva dal server, è stato possibile confrontare la documentazione con la risposta del server e usarla per decifrare la documentazione (e sì, decifrare era il termine giusto). Il problema era che se al server fosse stata inviata una richiesta che non era esattamente corretta secondo le specifiche, si otterrebbe un errore e, con la documentazione illeggibile, capire come inviare le richieste corrette era quasi impossibile. Esistevano anche diverse versioni della documentazione API che non erano d'accordo tra loro e probabilmente non erano d'accordo con l'API stessa; quello non ha aiutato.

Se ci fosse stato un comando che avrei potuto inviare al server, restituendo un elenco di tutti i comandi possibili e come inviarli esattamente, sarebbe stato estremamente utile. La rilevabilità non è solo per i clienti, ma è anche utile per gli sviluppatori di software.

NOTA: Non sono un esperto in materia, ma ho attraversato un processo analogo nel tentativo di conciliare le diverse sfumature delle interpretazioni della gente di "REST" qualche anno fa, e questo è il modo in cui ho ottenuto esaminando il tempo.

A quanto ho capito, questo deriva dall'Ipermedia di Roy Fielding come Engine of Application State, noto anche come "HATEOAS", che diventa quindi un fattore abilitante dell'idea di una "rete semantica".

Quindi ... in sostanza, e ancora una volta, come ho capito, tu fai la tua applicazione RESTful sostanzialmente auto-descrivendola in modo tale che il consumatore non debba avere una conoscenza preliminare di un contratto formale per consumare il tuo contenuto / funzionalità. Sono in grado di interagire da alcuni endpoint root predefiniti e quindi di eseguire collegamenti contestualmente rilevanti forniti dalla tua app mentre il consumatore interagisce. Il consumatore, ovviamente, può essere una persona o un agente sistemico.

Se si sta semplicemente utilizzando "REST" per URL piuttosto associati a operazioni CRUD di cui un consumatore deve avere una conoscenza preliminare e chiamate in base a un contratto ben noto, Roy Fielding lo considererebbe non realmente RESTful.

Questo non vuol dire che un servizio RPC aromatizzato con REST non possa essere utile / un miglioramento rispetto a un modello RPC più elaborato e adatto per un uso limitato / controllato, ma gli hardliner guarderanno il naso e lo considereranno degenerato / non proprio RIPOSO.