A Few Words on REST

REpresentational State Transfer

REST is the underlying architectural principle of the web.

It is formalized as a set of constraints, described inRoy Fielding's PhD dissertation.

Richardson Maturity Model

http://martinfowler.com/articles/richardsonMaturityModel.html

Levels 0, 1, and 2

• It is all about resources
• Client uses specific HTTP verbs
• Server uses HTTP status codes
• Content Negotiation

Level 3 - Hypermedia Controls

• Service discovery via relations
• Hypermedia formats (e.g. HTML, HAL, JSON-LD)
• Resources are not important, their representations are!
• URI design does not matter (URI template)
• Client's experience is crucial!
• Protocol & application semantics

HATEOAS

Hypermedia As The Engine Of Application State

It means that hypermedia should be used to find your way through the API. It is all about state transitions.

Your application is just a big state machine.

Application State

Resource State

Resource vs Representation

A resource can be anything, and can havemore than one representation. A representation describes resource state.

Protocol Semantics

How the underlying resource should behave under HTTP?

Application Semantics

What specifically will happen to application or resource state?

The Semantic Challenge*

Some standards have a good protocol-level semanticsbut no application-level semantics (Collection+JSON, Atom).

Some standards define a lot of application-level semantics but no protocol semantics (Microformats, Microdata).

* as described in Richardson and Amundsen's "RESTful Web APIs" book

Profiles

A profile is defined to not alter the semantics of theresource representation itself, but to allow clients tolearn about additional semantics, RFC 6906. It does not have to be machine-readable but it is recommended.

Examples

• Traditional API documentation
• XMDP (for XHTML documents)
• ALPS (XMDP on steroids)
• Embedded doc. (as in HAL/Siren)
• JSON-LD

How To Design A Web API?

1. List The Semantic Descriptors

2. Draw A State Diagram

• Each "box" represents one kind of representation
• Arrows are the state transitions (HTTP requests)
• Change descriptors to relations when it makes sense

3. Use Strings From Existing Profiles

4. Choose A Media Type

Don't define your own, please.

5. Write A Profile That DocumentsYour Application Semantics

6. Eat. Sleep. Code. Repeat.

7. Publish The "First" URL

Mmmmh

State Of The Art Industry

We all want RESTful APIs

Yes.

Is My API RESTful When I Use JSON?

Short answer: no. Long answer: no, not yet. RESTful API must use hypermedia formats. JSON isnot a hypermedia format, The REST CookBook.

s/REST/HTTP++/

REST APIs are a myth, i.e. too complex in real life.

99.99% of the RESTful APIs out there aren’t fully compliantwith Roy Fielding’s conception of REST, Steve Klabnik.

No Relations = No REST

If the engine of application state (and hence the API)is not being driven by hypertext, then it cannot beRESTful and cannot be a REST API, Roy Fielding.

Does It Matter?

Beyond The Constraints

Often Too Much

• How many clients do you have?
• Do you know any RESTful client?
• Writing smart clients is complicated

Real Life #1

Because of multiple round-trips and over-fetching,applications built in the REST style end up buildingad hoc endpoints, Facebook (on Relay/GraphQL).

Real Life #2

Pure REST: Slow, hard to program, and rare, Netflix.

Introducing HTTP++ APIs

Well-designed, pragmatic, and future-proof APIs.

Design your API from a client perspective

Think in terms of representations

Stick to HTTP

Still really want to build a RESTful API?

Choose the JSON-LD format.

So What?

It is ok not to build RESTful APIs

"REST" is a (marketing) buzzword

REST is not a silver bullet