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?

user62575
  • 285
  • 2
  • 6
  • 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! http://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](http://raml.org/) and [JSON schema](http://json-schema.org/). i haven't used them but they look somewhat promising. – JimmyJames Dec 19 '16 at 14:49
  • @Laiv I'm not sure I understand your statement. XML was 'schemaless' until is wasn't. There's nothing about JSON that makes it impossible to define a schema for it which is proven by the existence of JSON schema (see my answer above.) – JimmyJames Dec 19 '16 at 14:51
  • It might be worth you guys putting these suggestions in answers -- people can upvote and comment on each solution separately, which may help give others a fuller picture. I'll add in a couple for WSDL and WebIDL, and let you guys get the credit for the ones you've mentioned. – user62575 Dec 19 '16 at 14:54
  • 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
  • @JimmyJammes by schemaless I wanted to make reference to the abscence of contracts like WSDL. Would be more appropiated to speak about contractless? – Laiv Dec 19 '16 at 15:59
  • The thing is, if the industry has shift from webservices highly constrained by their contracts to something more flexible, applying contracts to the new webservices is an step back towards those implementations the industry is running away from. So, instead of looking for contracts between server and client, I rather suggested to look for mechanims for documentation or prototyping. That's it. – Laiv Dec 19 '16 at 16:19
  • @Laiv Also look at RAML. The question of using schemas and contracts is orthogonal to the choice of 'self-describing' serialization formats. It seems to be the case that people think that the reason to use JSON is because "there is no schema" but you can use XML without a schema. If the OP wants/needs a schema, there's nothing about JSON to prevent that. I am acutely aware of the pain of SOAP/WSDL but I think a few babies have been thrown out with the bath water. Sometimes a very loose specification is the right choice but not always. The idea that JSON docs must have no spec is just wrong. – JimmyJames Dec 19 '16 at 16:45
  • I can't argue that. Different contexts may need different approaches. Just I can't stop feeling that contracts brings too much overhead. It's one more layer to get rid of. – Laiv Dec 19 '16 at 16:57
  • @Laiv I think it really depends on the situation. When you are writing the front-end and the back-end, it makes no sense (at that time) because you already know what each side is doing. If there are teams that you work closely with using your specs, informal docs are probably good enough. Once you start adding large numbers of consumers that you don't have time to talk to, the value of formal specs increases. It helps you communicate changes and manage their impact. The problem is that it was sold as a way to automate integration which it could never do. – JimmyJames Dec 19 '16 at 19:08
  • If you have a strongly typed back end, how about (auto) generating flowtype interfaces from the service request and response types, and importing those interfaces in the javascript client app? The tooling is something like t4 templates (in .NET land) for code generation and the flowtype checker to validate correct interaction with service. – Andreas Warberg Dec 19 '16 at 22:35

6 Answers6

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.

Laiv
  • 14,283
  • 1
  • 31
  • 69
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.

Aaron Mansheim
  • 103
  • 2
JimmyJames
  • 24,682
  • 2
  • 50
  • 92
  • 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 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
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.

Matthew Will
  • 129
  • 2
  • For me, TypeScript definitions could be a great mechanism, especially if you can generate them from your server-side code -- https://github.com/ToTypeScriptD/ToTypeScriptD is a good example of that. – user62575 Dec 19 '16 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);
};
user62575
  • 285
  • 2
  • 6
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/

Rahul Kumar
  • 9
  • 1
-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>
user62575
  • 285
  • 2
  • 6