Come ottenere un'API REST liberamente accoppiata ma con un contratto definito e ben compreso?

4

Sono nuovo di REST e sto lottando per capire come si possa progettare correttamente un sistema REST sia per consentire un accoppiamento lento, ma allo stesso tempo consentire a un consumatore di un'API REST di comprendere l'API.

Se, nel mio codice cliente, emetto una richiesta GET per una risorsa e recupero XML, come faccio a sapere cosa fare con quel xml? per esempio. se contiene <fname>John</fname><lname>Smith</lname> come faccio a sapere che questi si riferiscono al concetto di "nome", "cognome"? Spetta alla persona che scrive l'API REST di definire nella documentazione in qualche posto cosa significano tutti i campi XML? Cosa succede se il produttore dell'API desidera modificare l'implementazione in <firstname> anziché <fname> ? Come fanno questo e notificano ai loro consumatori che questo cambiamento è avvenuto? Oppure i consumatori incontrano semplicemente l'errore e poi guardano il carico utile e capiscono da soli che è cambiato?

Ho letto in REST in Practice che usare uno strumento WADL per creare un'implementazione client basata sul WADL (e nascondere il fatto che si sta facendo una chiamata distribuita) è un "anti-pattern". Ma stavo progettando di farlo - almeno allora avrei una chiamata API tipicamente statica che, se fosse cambiata, saprei in fase di compilazione e non in fase di esecuzione. Perché è una cosa brutta generare un codice client basato su un WADL?

E come faccio a sapere cosa fare con i collegamenti restituiti nella risposta di un POST a un'API REST? Cosa definisce questo contratto e dà un vero significato a ciò che ogni link farà?

Per favore aiuto! Non capisco come passare da staticamente-digitato o anche da SOAP / RPC a REST!

    
posta BestPractices 11.08.2012 - 22:28
fonte

2 risposte

2

Avere un'architettura liberamente accoppiata, come nel caso di un server REST API e il suo client corrispondente, implica che entrambe le parti comprendano e rispettino un protocollo e una semantica comuni.

Se l'API modifica la semantica della sua risposta, il client deve esserne a conoscenza e rispondere di conseguenza.

Detto questo, gli strumenti si evolvono e cambiano. A causa della natura dell'architettura disaccoppiata, qualsiasi modifica sul produttore dell'API dovrebbe riflettersi sul consumatore. Tuttavia, per ragioni pratiche questo non è sempre possibile. Solitamente per modifiche davvero radicali, il produttore esporrà diversi endpoint API, rispecchiando la vecchia e nuova funzionalità dell'API. Questo basicale fa guadagnare tempo al consumatore, fino al punto che la vecchia API è completamente deprecata.

    
risposta data 11.08.2012 - 22:42
fonte
-1

What if producer of the API wants to change the implementation

Il produttore deve fornire versioni dell'API.

link

The majority of Web API initiatives leave versioning for later. I believe this is a dangerous idea for a variety of reasons. First and foremost, if you run just one version of an API you risk introducing a breaking change anytime you extend it. While you can potentially work around this with a very robust set of test cases (which I would strongly encourage), it is easy to paint yourself into a corner when you are unable to fix a bad implementation that seemed like a good idea at the time.

Se guardi l' API REST di Twitter , vedrai una versione numero nell'URL:

api.twitter.com/1.1/statuses/mentions_timeline.json

Ciò consente al produttore di modificare il formato dei dati di output man mano che l'API evolve. Le applicazioni che utilizzano l'API pubblicherebbero quindi aggiornamenti mentre si spostano verso versioni successive dell'API.

Per sapere come si intende ogni chiave dati, l'API dovrebbe essere documentata per mostrarti (1) cosa verrà restituito e amp; come si riferisce al loro servizio e (2) il formato di dati e dati richiesto per essere inviato al loro servizio.

    
risposta data 11.10.2012 - 00:22
fonte

Leggi altre domande sui tag