What are we doing in here?
Talking about REST, Web APIs, and the differences betwen them
Talking about how to build REST/HTTP/Web APIs in Java
simply
quickly
without a lot of "cruft" hanging around
but with the room to grow and scale if necessary
... with several examples
SparkJava
RestX
DropWizard
Vert.x
"Using elements of the client/server, pipe-and-filter, and distributed objects paradigms, this 'representational state transfer' style optimises the network transfer of representations of a resource. A Web-based application can be viewed as a dynamic graph of state representations (pages) and the potential transitions (links) between states. The result is an architecture that separates server implementation from the client's perception of resources, scales well with large numbers of clients, enables transfer of data in streams of unlimited size and type, supports intermediaries (proxies and gateways) as data transformation and caching components, and concentrates application state within the user agent components."
REST takes the position that the Web as it currently exists is all we really need--why reinvent the wheel?
URIs provide unique monikers on the network
HTTP provides commands and request/response
HTML/XML provides content format
a RESTful model seeks to establish "resources" and use the basic CRUD methods provided by HTTP (GET, POST, PUT, DELETE)
find an Employee:
GET /employeeDatabase?name='fred'
returned content body will be employee data
creating a new Employee:
PUT /employeeDatabase
content body is the employee data
modify an existing Employee:
POST /employeeDatabase?name='fred'
goal of RESTful system is to model the data elements
addressable resources (via URIs)
uniform interfaces that apply to all resources
manipulation of resources through representations
stateless self-descriptive messages
'representations'--multiple content types accepted or sent
in essence, we're organizing a distributed application into URI addressable resources that provide the full capabilities of that application solely through HTTP
this is a complete flip from traditional O-O
objects encapsulate data behind processors
REST hides processing behind data elements/structures
consider the World Wide Web:
well-established, well-documented, "debugged"
no new infrastructure to establish
payload-agnostic
well-defined solutions (HTTPS, proxies, gateways)
obviously extensible (WebDAV, explosive growth)
platform-neutral and technology-agnostic
it's hard to argue with success!
REST provides "anarchic scalability"
assumes there is no one central entity of control
architectural elements must continue operating when subjected to unexpected load ("the Slashdot effect")
REST allows for independent deployment
hardware/software can be introduced over time w/o breaking clients (the power of the URI and DNS)
not all participants need change/evolve simultaneously
REST returns us to simplicity
it's all URLs, HTTP, and HTML/XML; nothing else
REST depends a great deal on underlying technology
HTTP uses simple name/value pairs for headers
this leaves out complex headers (a la WS-Sec)
REST requires a loosely-bound API
"interface genericity"
no metadata constructs to key from
REST requires more work on your part
Part of the World Wide Web experiments
Designed to be:
simple
content-agnostic
platform-agnostic
referral (to another server) capability
minimal to zero administrative overhead
format negotiation
operate over standard infrastructure (TCP/IP)
HTTP 0.9: Original proposal (1991) by TBL
HTTP 1.0: 1991 - 1995 saw rapid growth/adoption
HTTP 1.1: Internet standard status (95 - 99)
numerous proposals to enhance 1.1 since
nothing officially adopted (or even taking root)
for better or for worse
to the point of supplanting other more specific protocols
FTP replaced by file transfer over HTTP
email protocols replaced by web clients and transfer
bidirectional sockets replaced by WebSockets (!)
designed by Roy Fielding as his Doctoral dissertation
explicit architectural goals
attempts to shoehorn additional features into HTTP meet with mixed success
and with Fielding's frustration and disdain
see Fielding's dissertation
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
see Architecture of the World Wide Web
http://www.w3.org/TR/webarch/
both are highly recommended reads
Let's see how we do simple REST endpoints with each
obviously each deserves deeper investigation
consider this a very incomplete introduction
Summary
Pick your poison:
simplicity vs features
development approach (spec vs code)
degree of JAX-RS correlation
Pick whether you want to do both APIs and classic server-generated HTML
some will do the latter better than others
Pick whether you need more than just HTTP
Vert.x is really your best bet there
Prototype, experiment, and explore
Who is this guy?
Architect, Engineering Manager/Leader, "force multiplier"
Principal -- Neward & Associates
http://www.newardassociates.com
Educative (http://educative.io) Author
Performance Management for Engineering Managers
Author
Professional F# 2.0 (w/Erickson, et al; Wrox, 2010)
Effective Enterprise Java (Addison-Wesley, 2004)
SSCLI Essentials (w/Stutz, et al; OReilly, 2003)
Server-Based Java Programming (Manning, 2000)