autoscale: true theme: Next, 3
REST
Defining Web Services
- System-to-system integration using HTTP
- Goal: cross-platform API consumption
- Originally defined using XML-based protocols
- Language and system neutral
Old School Web Services
- XML-Based
- Began to emerge at the dawn of the century
- Developed by the W3C Working Group and industry consortiums
Elements of XML Web Services
- Define standard request and response XML structures
- SOAP - Simple Object Access Protocol
- WSDL - Web Services Description Language
- UDDI - Universal Description, Discovery and Integration
Benefits of XML Web Services
- Good tooling support due to strict XML-schema-based protocol
- Well-structured payloads could be validated minimizing errors
- First viable attempt at cross platform interoperability
- Still used in many companies today
Problems with XML Web Services
- XML payloads proved to be too large:
- Excessive network load
- Difficult to read and debug issues
- Large standards bodies moved to slow
- Required too much buy in from too many parties
REST and JSON
REST
- Representational State Transfer
- Architectural style based strictly on HTTP and a common pattern
- Convention for defining URI mappings to resources
- HTTP method (verb) defines the action being requested by the client
Resources
- Key concept in REST
- Data of value at the end of a URL
- Individual item
- Collections
- Think Domain classes
REST Constraints
- Client-server
- Stateless
- Cacheable
- Uniform interface
- Layered System
- Code-On-Demand
Uniform Interface
- Self-descriptive messages (MIME types)
- Resource identifiers as an endpoint
- HTTP methods are used to signify intent
HTTP Methods
- GET - retrieve resource
- PUT - replace (update) resource
- POST - create new single resource
- DELETE - delete resource
Method Characteristics
- GET is safe
- Calling it produces no side-effects
- PUT and DELETE are idempotent
- Calling it repeatedly will produce the same result
URI Conventions
- Collection: /resources/
- GET: return a list
- POST: create a new item
- Items: /resources/id
- GET: return specific resource
- DELETE: delete specific resource
- PUT: update specific resource
Good URI Rules
- Unique to a resource
- Long-lived
- Always point to the same resource
REST Data Formats
- REST only addressed part of the problem with XML Web Services
- Complexity
- The rest of the problem lies in the complexity of the request and response payloads
- REST can be implemented with XML
- To complete the move to simpler APIs implement REST with JSON
JSON
- JavaScript Object Notation
- Lightweight data format
- Syntax, data types, format
- Only two structures:
- Objects and Lists
- Maps nicely to REST
JSON Value Types
- string
- number
- object
- array
- null
- true
- false
JSON Object Format
- String value mapping inside curly braces
{
"name": "Bill",
"age": 66,
"golfer": true,
"address": {
"country": "USA"
}
}
JSON List format
- Comma-separated values inside square brackets
[ 1, 2, 3, 'a', false]
[{"name": "Mike"}, {"name": "Lars"}]
REST Considerations
- Updates to domain model may unintentionally break clients
- Timeline for API changes may be different than timeline for business or domain changes
- May not want to expose all fields of domain model to clients
- Error handling/reporting a bit generic
- Parent child representation can be challenging
Approaches to Detaching API Payload
- Programmatically convert domain into payload
- Builder patterns can be useful here
- Create separate model for API payload (DTO approach)
- Modify the marshalling of the domain into destination format
Return Proper Status
- 200 : OK - response handled properly
- 201 : Created - return after a successful POST
- 400 : Bad Request - invalid parameters
- 403 : Unauthorized - failure to authenticate, not logged in
- 403 : Forbidden - missing required permission
- 404 : Not Found - item requested is missing
- 415 : Unsupported Media Type - data not in correct format
- 422 : Unprocessable Entity - failed validation
REST API Security
- Protect access
- Suggested: Basic HTTP Authentication
- Know who is making calls
- Reporting
- Throttling
- Suggested: API Key
Basic HTTP Authentication
- Client includes credentials in the header of every request
- Must use HTTPS to prevent sending of plain text credentials
- Spring Security provides an implementation of Basic HTTP Authentication
API Versioning
- New data formats may break existing clients
- Several options for solving
- Create new URL with a version URL path (/v2/songs)
- Rely on a request header from client to format the proper response
- Create a custom MIME type and respond with different renderings for each
- Honor the Accept HTTP header
REST Not Just for APIs
- Single Page commonly use REST within an app
- UIs are plain HTML and JavaScript (no server rendering)
- Server sends/receives data from browser via REST
Final Notes on REST
- Use the proper HTTP methods and response status code
- Use the header for client identification
- All parameters (other than id) should be specified as query parameters
- Use Postman (Chrome plugin) to quick test/debug non GET calls
- REST/JSON competitors exist and are becoming popular
Alternatives to REST/JSON
- Alternatives exist to go back to the RPC style of things
- Most offer backwards versioning and similar/better compression over HTTP
- Examples
- Protocol Buffers (Google)
- Thrift (Facebook)
- Avro (Apache)
- gRPC Google’s RPC exchange over HTTP2 (using protobufs)