Chapter 106. REST-like Concepts

Architectural Style for creating web services
Provide interoperability between computer systems on the Internet
Uses a uniform and predefined set of stateless operations
Defined in 2000 by Roy Fielding in his doctoral dissertation that was also used to design HTTP 1.1 ^[11]

106.2. "REST-like"

"HTTP-based"

REST officially contains much more than most interface designs use
- Leads to some common questions
  - "What is your definition of REST?"
  - "How RESTful are you?"
Common "REST-like" architectures are based on a few main principals
Uncommon REST features adopted
- Hyperlinks
  - Dynamic discovery of resource capabilities
Richardson MaturityModel ^[12]
- Level 0 - Using HTTP soley as a transport
- Level 1 - Using Resources
- Level 2 - Using HTTP Methods
- Level 3 - Using Hypermedia Controls

106.3. HTTP Protocol embraced

Previous commmunications protocols attempted to be transport agnostic
REST technically does not exist outside of the HTTP transport protocol
- Everything is expressed in HTTP-terms
- REST APIs leverage the world's investment into Internet communications

106.4. Resource

An asset to be exposed to the web
Web has limited number of methods but can have an unlimited number of resources
Example Resources
Resources can be nested
* Conceptual representation

106.5. Uniform Resource Indentifiers (URIs)

the "Nouns" of what we are communicating

An address (of varying detail) to access a particular resource
Technically, URIs can be either URNs or URLs
- Uniform Resource Name ^[13]
  - Resource identity
  - Globally unique
  - Example:
    urn:info.ejava.products:1 <core xmlns="urn:activemq:core">
- Uniform Resource Locator ^[14]
  - Resource's location on a network
  - Contains protocol information -- "how to get it"
  - Example:
    http://127.0.0.1/jaxrsInventoryWAR/api/products/1 https://127.0.0.1/jaxrsInventoryWAR/api/products/1 ftp://127.0.0.1/info.ejava.products:1
- Commonly -- URIs are a partial URL
  - Commonly lack protocol and physical location
  - Relative to some point in the application
  - Example:
    /jaxrsInventoryWAR/api/products/1 /api/products/1 products/1

Example resource collection URI

/api/products
/api/categories
/api/customers
/api/todo_lists

Example individual resource URIs (with mandatory path {parameter}s

/api/products/{productId}
/api/categories/{categoryId}
/api/customers/{customerId}
/api/customers/{customerId}/sales

Example nested resource URIs

/api/products/{productId}/instructions
/api/categories/{categoryId}/products
/api/customers/{customerId}/purchases
/api/todo_lists/{listName}/todo_items

URIs may express variable parameters

Use query parameters for optional variables

http://127.0.0.1:8080/jaxrsInventoryWAR/api/categories?name=&offset=0&limit=0

Nested path parameters may express mandatory variables

http://127.0.0.1:8080/jaxrsInventoryWAR/api/products/{id}
http://127.0.0.1:8080/jaxrsInventoryWAR/api/products/1
id=>1

URI naming conventions
- Use a plural name for resource collections
```
/api/todo_lists
```
- Use an ID below the plural resource collection to refer to a specific resource
```
/api/todo_lists/{listName}
```

106.6. Methods

the "Verbs" of what we are communicating

Bounded Set
- provides "uniform interface" across all resources
Primary Set of Methods
Secondary Set of Methods
- HEAD - a GET without the data - metadata only
- OPTIONS - lists which methods supported

Example: Get Product ID=1

GET http://127.0.0.1:8080/jaxrsInventoryWAR/api/products/1

106.6.1. Method Safety

Does the method change the state of the resource?

Safe Methods
Unsafe Methods

Do not violate default method safety expectations

Internet communications is based upon the above method saftey expectations, but these are just definitions. You have the power to implement resource methods any way you wish. However, avoid violating these method expectations -- or your API will not be immediately understood and will render built-in Internet capabilities (e.g., caches) useless. The following are examples of what *not* to do:

GET /jaxrsInventoryWAR/api/products/1?command=DELETE
POST /jaxrsInventoryWAR/api/products/1
  content: {command:'getProduct'}

106.6.2. Idempotent

Design goal for each method implementation -- regardless of "safety"
Method will result in the same resource ending state no matter how many times executed
Idempotent methods
Non-Idempotent method(s)
- POST

Relationship between Idempotent and browser page refresh warnings?

The standard convention of Internet protocol is that all methods except for POST are assumed to be idempotent. That means a page refresh for a page obtained from a GET gets immediately refreshed and a warning dialogue is displayed if it was the result of a POST.

106.8. Links

REST-like applications likely stop at providing standard links in HTTP headers

POST http://localhost:8080/ejavaTodos/api/todo_lists
{"name":"My First List"}
=>Created/201
Location: http://localhost:8080/ejavaTodos/api/todo_lists/My%20First%20List
Content-Location: http://localhost:8080/ejavaTodos/api/todo_lists/My%20First%20List

Content-Location - direct URL for the data returned in the payload
Location - a re-direct to a new URL
- Result of a new resource being created

106.9. Summary

Terms "REST" and "RESTful" have a specific meaning defined by Roy Fielding
Very few APIs achieve full REST adoption -- but that is OK!!! -- just call it "REST-like" or "HTTP-based"
Most serious REST-like APIs adopt

^[10] Representational State Transfer Wikipedia Page

^[11]"Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation", Roy Thomas Fielding, University of California, Irvine, 2000 HTML Version

^[12] Richardson Maturity Model

^[13] URN Wikipedia Page

^[14] URL Wikipedia Page