Designing REST Services for Architects Training

An increasing number of services take a RESTful approach to data transmission. Representational state transfer (REST) is a style of software architecture that differs from the more traditional Remote Procedure Call (RPC) style of data transmission, instead emphasizing the importance of defining and retrieving representations of resources. In this course, we present a concise view of the REST topics that are important to the architects.

Chapter 1. REST Services

• Many Flavors of Services
• Understanding REST
• Principles of RESTful Services
• REST Example – Create
• REST Example – Retrieve
• REST Example – Update
• REST Example – Delete
• REST Example – Client Generated ID
• SOAP Equivalent Examples
• REST Example – JSON
• REST vs SOAP Communication
• More REST vs SOAP
• REST vs SOAP Summary
• Famous RESTful Services
• Additional Resources
• Summary

Chapter 2. JSON

• Introduction
• JavaScript Object Notation (JSON)
• JSON Syntax
• How Does JSON Based Communication Work?
• JSON API in HTML5
• How Does JSON Based Communication Work?
• JSON: Server Side
• JSON: Client Side
• JSON-Schema – Introduction
• JSON-Schema – Keywords
• JSON-Schema – Data Types
• JSON – Example
• JSON-Schema – Example
• JSON-Schema – Runtime Usage (Java)
• JSON-Schema Runtime Usage – Node.js
• Summary

Chapter 3. Security for REST Services

• RESTful Web Service API Refresher
• Securing REST Services
• Basic API Authentication w/ TLS
• OAuth1.0a
• OAuth2
• Custom Protocols
• Why use API Keys vs. Username/Password Authentication
• Storing your API Security Key
• Using IDs
• Sessions and URLs
• OAuth2 Overview
• OAuth – Facebook Sample Flow
• OAuth Versions
• OAuth2 Components
• OAuth2 – End Points
• OAuth2 – Tokens
• OAuth – Grants
• Authenticating Against an OAuth2 API
• Authentication using Node.js
• Authentication using Node.js (Contd.)
• OAuth2 Support in Spring Boot
• JSON Web Tokens
• JSON Web Token Architecture
• How JWT Works
• JWT Header
• JWT Payload
• JWT Example Payload
• JWT Example Signature
• How JWT Tokens are Used
• Adding JWT to HTTP Header
• How The Server Makes Use of JWT Tokens
• What are “Scopes”?
• Using JWT with Node.js – Installing and Importing JWT
• Using JWT with Node.js – Sample Service Method
• Using JWT with Node.js – Sample Middleware Method
• Summary

Chapter 4. Designing a RESTful Service

• Introduction
• The Design Methodology
• Ingredients of a Service Operation Interface
• REST Resource
• What Constitutes a REST Resource
• Resource Identifiers
• REST Resource Naming Best Practices
• Parameters
• HTTP Methods
• HTTP Headers
• MIME Types
• API Response Codes
• Example Operation Interface Document
• Formal (Machine-Readable) Specifications
• Formal (Machine-Readable) Specifications (cont'd)
• Data Modeling - BEFE
• Data Modeling (cont'd)
• Data Modeling - Back-End
• Canonical Data Model
• Canonical Data Model vs. Message Model
• RESTful Message Model
• Practicality of the Canonical Data Model
• Developing the Message Model
• Summary

Chapter 5. Soft Considerations in API Design

• Introduction
• Beyond Technical Issues
• Design Considerations for RESTful API
• Design Considerations for RESTful API (cont'd)
• Working on a Network is Different
• The Eight Fallacies of Distributed Computing
• The Eight Fallacies of Distributed Computing (cont'd)
• The Network is Not Reliable
• Latency is Not Zero
• Latency Varies Inside the Architecture
• Latency Impact on API Design
• The Network is Not Secure
• Bandwidth is Not Infinite
• Other Considerations - The Consumer
• Example: A Project Time Tracker
• Example 1
• Example 2
• Ease of Using the Message Data
• Usability vs Extensibility
• Going Too Far for the Client
• Other Considerations - Extensibility
• YAGNI
• Other Considerations - Error Handling and Idempotency
• HTTP and Idempotency
• Universally Unique Identifiers
• Bulk Operations and Large Responses
• Bulk Operations
• Bulk Operations (cont'd)
• Batch Protocols
• Large Queries
• Large Queries (cont'd )
• Summary

Chapter 6. Swagger

• Swagger / OpenAPI
• Swagger / OpenAPI Tools
• Swagger Editor
• YAML Basics
• OpenAPI Specification – Minimal Specification
• Operation Specification - Example
• Adding Parameters to the Operation
• Adding a Path Parameter to the Operation
• Defining a body Parameter
• Creating Reusable Data Model
• Reusing the Data Model
• Creating Reusable Parameters
• Reusing the Parameters
• Generating Server / Client Code
• Swagger UI – Introduction
• Swagger UI - Generating REST API Documentation
• Summary

Chapter 7. Manually Test REST API

• Introduction to RESTful Testing
• API Testing Tools
• API Testing with Postman
• Postman – Posting Data
• Postman – Response
• API Testing with cURL
• Using cURL - Basics
• Curl – POST
• Performing PUT & DELETE Operations
• Introduction to Advanced REST Client
• Summary

Lab Exercises

Lab 1. A Simple RESTful API in Spring Boot
Lab 2. JSON
Lab 3. OAuth2
Lab 4. Swagger / OpenAPI Specification
Lab 5. Manually Test an API