7

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. For example, let's say you are on a client-side team writing the JavaScript & HTML for a AJAX SPA app. Another team writes the back end -- say, in Java. It's important that the data you see returned from those services meets a certain 'shape.' For example, a call to

/Person/Read/79

should return

{
    "id": 79
    "firstName": "Anita",
    "lastName": "Hero"
}

How can the server team communicate this 'interface' to the JavaScript team? something like;

interface person {
    firstName: string;
    lastName: string;
    id: int;
}

I'm looking for a formal contract between the teams, so that the JavaScript team can build components, pages, and tests, confident that the server team will deliver real data in the expected shape.

I'm guessing this is already done in situations where there is are large teams on both sides, but I'm not aware of current approaches.

I'm currently aware of these standards, but I'm unsure which are active;

  • WSDL is an XML-based description, but since XML web services are dying in favour of JSON, and WSDL always seemed heavyweight, is it irrelevant for JSON-based dev?
  • WebIDL is the languge used to specify HTML5, so it's bang up to date, but are there any tools for it?
  • JSONSchema looks promising but again, what's the tooling like?
  • Swagger looks good -- thanks to @Laiv for the pointer.

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

closed as too broad by gnat, user22815, Thomas Owens Mar 22 '17 at 15:18

Please edit the question to limit it to a specific problem with enough detail to identify an adequate answer. Avoid asking multiple distinct questions at once. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.

  • One of the reason to use JSON as media type is that It's schemaless. If problem is documentation and comunication among teams, there are tools like Swagger that may help with both. – Laiv Dec 19 '16 at 13:34
  • Swagger looks like a great lead. Thanks! swagger.io – user62575 Dec 19 '16 at 14:32
  • The term I would look for is: API Rest prototyping or Documentation. Swagger is one of the many. – Laiv Dec 19 '16 at 14:33
  • Check out RAML and JSON schema. i haven't used them but they look somewhat promising. – JimmyJames Dec 19 '16 at 14:49
  • 6
    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. – Robert Harvey Dec 19 '16 at 15:12
7

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 hit the nail on the head.

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

I suggested Swagger in the comments. With Swagger, I'm proposing a developer-friendly approach. Something developers can interact with. Also, tackle and consume. Take a look at Swagger Editor and Swagger-Inspector for testing (a sort of Postman)

It's documentation by prototyping. Note that Swagger Editor also provides you with a client and stub server generator. However, the key feature of Swagger is the Swagger-UI. It is a web UI which allows us to do calls to the API. Unlike Swagger-Inspector, Swagger-UI is more user-friendly.

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

Should be fairly doable for you to deploy a NodeJS web server and deploy both elements, Swagger-UI and the API schema (JSON file). Don't you worry if during the early stages of the development, there is no server providing data. You can either generate a stub server with Swagger Editor or to build your own. I don't like to reinvent the wheel so, searching and reading about test doubles, I found Mountebank.

Later, just switch Swagger-UI settings to feed it with the real API server.

The idea is prototyping the API at the same time developers get familiar with it, get some feelings about how is going to be consumed, to suggest improvements or to tackle it. If the documentation is available online it's easy to make it accessible to everybody.

Note that documentation is usually addressed to a specific consumer. Swagger is a good documentation and design tool for developers. For regular or end-users, I would consider traditional documentation in HTML or PDF, with more literature about the API and how to use it. But, don't you worry, there are available several converters to transform Swagger Data model into HTML, PDF, ASCIIDOC and Markdown

3

I can't vouch for these as I have not used them, but there is a JSON schema specification which is used as part of the RAML RESTful interface spec. I know there are tools which will generate RAML for web services in various languages, but again, I can't vouch for how well they work.

As far as tooling goes around JSON-schema, my experience says it doesn't matter. This is a little controversial, and a lot of people think I am crazy when I say this, but tools that attempt to create code from schemas (schemata, for the pedants) and schemas from code are not worth using, in my experience, although the former is less problematic at a high level. I actually believe this is where things really went wrong with XML, although SOAP/WSDL was ill-conceived from the get-go and XML is hopelessly overcomplicated for integration tasks.

I think the failures of SOAP/WSDL and XML are informative, though. I think the key lesson is that tools exist to help you, not to lead you. Creating a fast, logical interface that meets the needs of the clients is your primary concern. If you spend a lot of time trying to get some magical code generation thingy running, you'll still have all the hard work to do with less time and more constraints.

  • a lot of people think I am crazy when I say this but tools that attempt to create code from schemas (schemata for the pendants) and schemas from code are not worth using welcome to the club – Laiv Dec 19 '16 at 17:04
  • I offered an edit to the text that Laiv quoted. P.S. Maybe I'm one of "the pendants" :-) – Aaron Mansheim Apr 17 '18 at 19:57
  • 1
    @AaronMansheim [Sigh]. good catch. I didn't like the removal of the double space after a sentence. That's just good form but whatever. – JimmyJames Apr 17 '18 at 20:13
1

We have had several developers in our organization be successful with using TypeScript and the interfaces that are available there. It will let you define the interface as such:

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

The added benefit of using TypeScript in your code is that if a field is renamed, your code referencing the old field name will break.

0

WebIDL is the languge used to specify HTML5, so it's bang up to date, but are there any tools for it?

An example WebIDL fragment looks like this;

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);
};
0

If you do not have to stick to JSON, you can have a look at Protocol buffers. With these so called protos you can write the format of the messages and can generate JS and Java classes which will read/write such messages. And they seems to be faster. Quick reference : https://developers.google.com/protocol-buffers/

  • I didn't know they did that! Nice. – user62575 Dec 20 '16 at 7:23
-2

WSDL is an XML-based description, but since XML web services are dying in favour of JSON, and WSDL always seemed heavyweight, is it irrelevant for JSON-based dev?

An example WSDL fragment:

<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>

Not the answer you're looking for? Browse other questions tagged or ask your own question.