Objectives

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

REST

"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

In other words...

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

REST

In other words...

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'

REST

"Resource Modeling"

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

REST

There's something to be said for this model

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

Advantages

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

Disadvantages

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

HTTP

HyperText Transfer Protocol

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

HTTP has seen few revisions

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)

HTTP

HTTP is now the de facto standard protocol of the Internet

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 (!)

HTTP

HTTP is the protocol part of a REST system

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

HTTP

For more on HTTP concepts

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

Practice

Let's see how we do simple REST endpoints with each

obviously each deserves deeper investigation

consider this a very incomplete introduction

Summary

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

Credentials

Who is this guy?

Architect, Engineering Manager/Leader, "force multiplier"

Co-founder, Solidify US

http://www.solidify.dev

Principal -- Neward & Associates

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)

See http://www.newardassociates.com