Qual è la necessità di "rilevabilità" in un'API REST quando i client non sono abbastanza avanzati da farne uso in ogni caso?

La necessità di rilevabilità potrebbe non essere pertinente, ma i collegamenti che consentono la rilevabilità hanno più scopi. Il più importante di questi, a mio avviso, è che fornire URI completi nelle risposte al client, significa che nessun client dovrà mai "comporre" un URI. Ciò significa che nessun cliente avrà mai bisogno di sapere come sono strutturati gli URI. E questo a sua volta consente agli sviluppatori del server di modificare lo schema URI ogni volta che gli conviene, dato che non hanno bisogno di considerare che i client più vecchi si affidino ancora a un vecchio modo di strutturare gli URI.

I "client" potrebbero non essere abbastanza avanzati per farne uso, ma gli utenti dei client possono. Un cliente può essere qualcosa di semplice come un browser web, dopo tutto. La rilevabilità consiste nel 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, postfix l'URL con "/ api", e ottieni una pagina che descrive tutto ciò che puoi fare. Rende banale l'apprendimento dell'API. Ad esempio, il link ti porta al server jenkins per jruby e link ti porta all'api per quella specifica pagina.

NOTA: Non sono un esperto in materia, ma ho attraversato un processo simile per cercare di riconciliare le diverse sfumature delle interpretazioni della gente del "REST" alcuni anni fa, e questo è l'asporto che ho avuto dall'osservare in quel momento.

A mio parere, questo deriva da Hypermedia come Motore dello stato dell'applicazione alias "HATEOAS" di Roy Fielding, che poi diventa un facilitatore dell'idea di un "web semantico".

Quindi ... fondamentalmente, e ancora una volta, a quanto ho capito, rendi la tua applicazione RESTful fondamentalmente auto-descrivente 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 eseguire il commit da un endpoint root predefinito e quindi di accedere a collegamenti contestualmente rilevanti forniti dall'app durante l'interazione dell'utente. Il consumatore, ovviamente, può essere una persona o un agente sistemico.

Se stai usando solo "REST" per gli URL piuttosto mappati alle operazioni CRUD che un utente deve avere una conoscenza precedente e chiama secondo un contratto ben noto, Roy Fielding lo riterrà non veramente 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 a un uso limitato / controllato, ma i sostenitori della linea dura guarderanno il loro naso e lo considereranno essere degenerato / non proprio REST.

Ho avuto il piacere qualche tempo fa 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ì, decifrarla era il termine giusto). Il problema era che se una richiesta veniva inviata al server che non era esattamente corretta in base alle specifiche, si otteneva solo un errore e con la documentazione illeggibile, capire come inviare le richieste corrette era quasi impossibile. C'erano anche diverse versioni della documentazione API che non erano d'accordo e probabilmente non erano d'accordo con l'API stessa; quello non ha aiutato.

Se ci fosse stato un comando da inviare al server, restituendo un elenco di tutti i comandi possibili e con quale precisione inviarli, sarebbe stato estremamente utile. La rilevabilità non è solo per i clienti, è anche utile per gli sviluppatori di software.