9

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?

13
  • 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
    Commented Dec 19, 2016 at 13:34
  • Swagger looks like a great lead. Thanks! swagger.io
    – user62575
    Commented Dec 19, 2016 at 14:32
  • The term I would look for is: API Rest prototyping or Documentation. Swagger is one of the many.
    – Laiv
    Commented Dec 19, 2016 at 14:33
  • Check out RAML and JSON schema. i haven't used them but they look somewhat promising.
    – JimmyJames
    Commented Dec 19, 2016 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. Commented Dec 19, 2016 at 15:12

6 Answers 6

8

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 us with a client and a stub server generator. However, the key feature 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 data to provide with You can either generate a stub server with Swagger Editor or build one with Node. Since I dislike to reinvent the wheel I found Mountebank while searching about test doubles and stub servers.

Later on, switch the settings of Swagger-UI to feed it with the real API server instead of the fake one.

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, suggest improvements or to tackle it. If the documentation is available online it's easy to make it accessible to everybody.

Note that each 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 converters to transform Swagger Data model into HTML, PDF, ASCIIDOC and Markdown.

4

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.

3
  • 1
    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
    Commented Dec 19, 2016 at 17:04
  • I offered an edit to the text that Laiv quoted. P.S. Maybe I'm one of "the pendants" :-) Commented Apr 17, 2018 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
    Commented Apr 17, 2018 at 20:13
2

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.

1
  • For me, TypeScript definitions could be a great mechanism, especially if you can generate them from your server-side code -- github.com/ToTypeScriptD/ToTypeScriptD is a good example of that.
    – user62575
    Commented Dec 19, 2016 at 17:04
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/

1
  • I didn't know they did that! Nice.
    – user62575
    Commented Dec 20, 2016 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.