Praktisches & Grundsätzliches zur Informatik

Best Practice Component Interface Protocols: REST with JSON

REST and JSON replace SOAP and XML

Enterprise Software architects (such as e.g. Tom Marrs) say: Due to the rise of JSON Schema, XML has now become legacy.

I won't create new XML-based Web Services anymore unless someone absolutely requires it.

Initially, JSON was (and still is) great for Web applications, but due to JSON Schema, JSON is now a first-class player across the enterprise. JSON Schema enables architects and developers to provide a structure for the data exchanged between a Web Service and its consumers. JSON is (as of 2013) the dominant format for Streaming APIs.

JSON is a Javascript friendly data format fitting cleanly with HTML5 mobile applications (JSON-formatted data can be manipulated directly by Javascript — mappings from and to XML are no longer necessary).

JavaScript's rise in popularity is definitely leading to increased JSON usage, but so is the rise of RESTful Web Services. REST and JSON go hand-in-hand because they are made for each other. They're light, easy to use and understand, standards-based, and enterprise-class.

See also:
See also current Trend Reports:  REST vs SOAPXML vs JSONBeyond JSONEAI 2014

Schönes Beispiel für ein REST und JSON nutzendes Web API ist Microsofts Service Management API zu Azure. Es zeigt recht deutlich, dass eine JSON File eigentlich nur eine eingerückte Liste ist. Noch ein­facher geht es nun wirklich nicht.

Source: 3SCALE explaining Business APIs (2014)

Single Page Applications (Apps) lassen sich grob wie folgt charakterisieren (zitiert aus Osmanis Buch Developing Backbone.js Applications):

Not so long ago, the term » data-rich web application « was an oxymoron. Today, these applications are everywhere and you need to know how to build them.

Traditionally, web applications left the heavy-lifting of data to servers that pushed HTML to the browser in complete page loads. The use of client-side JavaScript was limited to improving the user experience. Now this relationship has been inverted – client applications pull raw data from the server and render it into the browser when and where it is needed.

Think of the Ajax shopping cart which doesn’t require a refresh on the page when adding an item to your basket. Initially, jQuery became the go-to library for this paradigm. Its nature was to make Ajax requests then update text on the page and so on. However, this pattern with jQuery revealed that we have implicit model data on the client side. With the server no longer being the only place that knows about our item count, it was a hint that there was a natural tension and pull of this evolution.

The rise of arbitrary code on the client-side which can talk to the server however it sees fit has meant an increase in client-side complexity. Good architecture on the client has gone from an afterthought to essential – you can’t just hack together some jQuery code and expect it to scale as your application grows. Most likely, you would end up with a nightmarish tangle of UI callbacks entwined with business logic, destined to be discarded by the poor soul who inherits your code.

Thankfully, there are a growing number of JavaScript libraries that can help improve the structure and maintainability of your code, making it easier to build ambitious interfaces without a great deal of effort. Backbone.js has quickly become one of the most popular open-source solutions to address these issues ...

Warum aber geschieht heute, was lange Zeit verpönt war (nämlich neben Code für die Präsenta­tion von Daten auch Code für deren Verarbeitung, für die Geschäftslogik also, in den Client zu legen)? Der Grund hierfür ist einfach:

Die Client/Server-Schnittstelle muss heute

auch Schnittstelle zwischen  G e s c h ä f t s p a r t n e r n  sein können.

Damit die dann aber auch stets aktuelle, ausreichend detaillierte und über alle Unternehmen hinweg einheitlich gestaltete Dokumentation der REST APIs vorfinden, sollte man sie unbedingt per RAML beschreiben und daraus dann HTML generieren. Wie so ein REST API dann durch Benutzer verstehbar wird, zeigt sehr schön ein Beispiel (die farbigen Buttons führen zu ausreichend genauer Dokumentation wirklich aller formalen Details der entsprechenden Funktionen).

Und natürlich kann im Anschluss an die formalen Details — wo notwendig oder hilfreich — auch jede Menge anwendungstechnischer Semantik von Funktion und Daten erklärt sein.

Read also:
Wissenswertes zu "Best Practice Component Interface Protocols: REST with JSON" zusammengestellt durch Gebhard Greiter.
tags: JSON1gegreit REST1gegreit API1gegreit