In che modo i grandi team di ingegneri descrivono l'interfaccia / contratto tra un servizio Web e il codice JavaScript del client? [chiuso]

I'm looking for a formal way for a front-end and a back-end team to communicate on the shape of a JSON web API

@RobertHarvey ha colpito il chiodo sulla testa.

Unless this is a public API, the usual way to communicate a contract is to document it. That works no matter how large the team is; in fact, the larger the team, the better it works

Ho suggerito Swagger nei commenti. Con Swagger, sto proponendo un approccio facile da sviluppatore . Qualcosa con cui gli sviluppatori possono interagire. Inoltre, affrontare e consumare. Dai un'occhiata a Swagger Editor e Swagger- Ispettore per i test (una specie di postino)

È documentazione di prototyping . Si noti che Swagger Editor fornisce anche un generatore di server client e stub. Tuttavia, la caratteristica fondamentale di Swagger è Swagger-UI . È una interfaccia utente web che ci consente di effettuare chiamate all'API. A differenza di Swagger-Inspector, Swagger-UI è più user-friendly.

So are there any descriptions of how this is communicated across distinct client-side and server-side teams?

Dovrebbe essere abbastanza fattibile per distribuire un server web NodeJS e distribuire entrambi gli elementi, Swagger-UI e lo schema API (file JSON). Non ti preoccupare se durante le prime fasi dello sviluppo non ci sono server che forniscono dati. Puoi generare un server stub con Swagger Editor o crearne uno tuo. Non mi piace reinventare la ruota quindi, cercando e leggendo i test double, ho trovato Mountebank .

In seguito, basta cambiare le impostazioni di Swagger-UI per alimentarlo con il vero server API.

L'idea è la prototipazione dell'API nello stesso tempo in cui gli sviluppatori si familiarizzano con esso, provano sentimenti su come verranno consumati, suggeriscono miglioramenti o affrontarli. Se la documentazione è disponibile online è facile renderla accessibile a tutti.

Si noti che la documentazione viene solitamente indirizzata a un consumatore specifico. Swagger è una buona documentazione e uno strumento di progettazione per gli sviluppatori. Per gli utenti regolari o finali, prenderei in considerazione la documentazione tradizionale in HTML o PDF, con più letteratura sull'API e su come usarla. Ma non preoccuparti, sono disponibili diversi convertitori per trasformare il modello Swagger Data in HTML, PDF, ASCIIDOC e Markdown

Non posso garantire per questi perché non li ho usati, ma esiste una specifica schema JSON che è usato come parte delle specifiche dell'interfaccia RAML RESTful. So che ci sono strumenti che generano RAML per servizi web in varie lingue, ma ancora una volta, non posso garantire per quanto bene funzionano.

Per quanto riguarda gli strumenti che ruotano attorno allo schema JSON, la mia esperienza dice che non ha importanza. Questo è un po 'controverso, e molte persone pensano che io sia pazzo quando dico questo, ma gli strumenti che tentano di creare codice da schemi (schemi, per i pedanti) e schemi dal codice non valgono la pena di usare, secondo la mia esperienza, anche se il primo è meno problematico ad alto livello. In realtà credo che questo sia il punto in cui le cose sono andate davvero male con XML, anche se SOAP / WSDL è stato mal concepito dall'ottenere -go e XML è irrimediabilmente complicato per le attività di integrazione.

Penso che i fallimenti di SOAP / WSDL e XML siano ben informati, comunque. Penso che la lezione chiave sia che esistono strumenti per aiutarti, non per guidarti. La creazione di un'interfaccia logica e rapida che soddisfi le esigenze dei clienti è la tua preoccupazione principale. Se passi un sacco di tempo a cercare di far funzionare qualcosa di magico in codice, avrai ancora tutto il duro lavoro da fare con meno tempo e più vincoli.

Diversi sviluppatori della nostra organizzazione hanno avuto successo nell'usare TypeScript e le interfacce disponibili Là. Ti permetterà di definire l'interfaccia in questo modo:

interface SquareConfig {
    color?: string;
    width?: number;
}

Il vantaggio di utilizzare TypeScript nel codice è che se un campo viene rinominato, il codice che fa riferimento al vecchio nome del campo si interromperà.

WebIDL è la lingua utilizzata per specificare HTML5, quindi è aggiornato, ma ci sono strumenti per vero?

Un esempio di frammento WebIDL assomiglia a questo;

exception GraphicsException {
  DOMString reason;
};

interface Paint { };

interface SolidColor : Paint {
  attribute float red;
  attribute float green;
  attribute float blue;
};

interface Pattern : Paint {
  attribute DOMString imageURL;
};

[Constructor]
interface GraphicalWindow {
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;

  attribute Paint currentPaint;

  void drawRectangle(float x, float y, float width, float height);

  void drawText(float x, float y, DOMString text);
};

Se non è necessario attenersi a JSON, è possibile dare un'occhiata ai buffer del protocollo. Con questi cosiddetti protos è possibile scrivere il formato dei messaggi e generare classi JS e Java che leggeranno / scriveranno tali messaggi. E sembrano essere più veloci. Guida rapida: link

WSDL è una descrizione basata su XML, ma poiché i servizi Web XML stanno morendo a favore di JSON e WSDL è sempre sembrato pesante, è irrilevante per gli sviluppatori basati su JSON?

Un esempio di frammento WSDL:

<operation name="sayHello">
     <soap:operation soapAction="sayHello"/>
     <input>
        <soap:body
           encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
           namespace="urn:examples:helloservice"
           use="encoded"/>
     </input>

     <output>
        <soap:body
           encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
           namespace="urn:examples:helloservice"
           use="encoded"/>
     </output>
  </operation>