rest-fundamentals.md

RESTful Web APIs

Introduction to RESTful Web APIs

What is REST?

• Representational state transfer:
  • Originally for accessing and manipulating textual representations of Web resources using a set of stateless operations
  • Today: More generic, encompassing every entity that can be identified, named, addressed or handled, in any way whatsoever, on the Web
• Architectural pattern, not a standard
  • Request-response pattern
• Today, HTTP-based RESTful APIs dominate
  • URLs for addressing
  • JSON, sometimes XML for representing data elements
  • Standard HTTP methods aka verbs (e.g. GET, PUT, POST, and DELETE)
  • Standard HTTP status codes for representing results
  • HTTP header fields (standard or custom) for sending parameters
  • TLS for encrypting data in-transit

Important Tools (Examples)

• API Clients
  • Postman
  • Insomnia
  • REST Client in Visual Studio Code
• Web Debugger
  • Fiddler
• Post Dumping Services
  • requestb.in

Sample Requests

<!--#include file="rest-fundamentals/0010-rest-clients/pokeapi.http" -->

<!--#include file="rest-fundamentals/0010-rest-clients/northwind.http" -->

Exercise: Try this sample with different REST clients

Sample Requests (cont.)

<!--#include file="rest-fundamentals/0010-rest-clients/post.http" -->

Exercise: Try this sample with different REST clients

Important REST principles

• Stateless
  • No client context stored on the server
  • Each request is complete
• Cacheable
  • Responses explicitly indicate their cacheability
• Layered System
  • Client cannot tell if connected directly to the server (e.g. reverse proxies)
• URIs
  • Resources are identified using Uniform Resource Identifiers (URIs)
• Resource representation
• XML, JSON, Atom - today mostly JSON

RESTful Web APIs in the Browser

• Old but still relevant: XMLHttpRequest
• Newer, but only in modern browsers: fetch
  • Detailed MDN documentation about fetch...

<!--#include file="rest-fundamentals/0020-rest-client/app-promise.js" -->

RESTful Web APIs in the Browser (cont.)

With async/await:

<!--#include file="rest-fundamentals/0020-rest-client/app.js" -->

RESTful Web APIs in the Browser (cont.)

With jQuery:

<!--#include file="rest-fundamentals/0020-rest-client/app-jquery.js" -->

Building RESTful Web APIs with Node.js

• In practice, frameworks are used for that
• Example: Express.js
  • Larger framework, not just for RESTful Web APIs
  • Very commonly used
  • Lots of plugins
• Example: restify
  • Smaller framework specialized on RESTful Web APIs
  • Easy to use
  • Also quite common
  • We will use this framework in this course

RESTful Web API with restify

<!--#include file="rest-fundamentals/0030-restify-basics/app.ts" -->

<!--#include file="rest-fundamentals/0030-restify-basics/request.http" -->

RESTful Web API with restify

• server object
  • Register routes and handlers for incoming requests
  • Created using the createServer() method
  • Documentation
• request object
  • Represents the HTTP request
  • Use it to get headers, parameters, body, etc.
  • Documentation
• response object
  • Represents the HTTP response
  • Use it to build response (e.g. status, headers, body, etc.)
  • Documentation

restify Examples

<!--#include file="rest-fundamentals/0040-restify-verbs/app.ts" -->

restify Examples (cont.)

<!--#include file="rest-fundamentals/0040-restify-verbs/data.ts" -->

<!--#include file="rest-fundamentals/0040-restify-verbs/get-all.ts" -->

restify Examples (cont.)

<!--#include file="rest-fundamentals/0040-restify-verbs/get-single.ts" -->

restify Examples (cont.)

<!--#include file="rest-fundamentals/0040-restify-verbs/post.ts" -->

restify Examples (cont.)

<!--#include file="rest-fundamentals/0040-restify-verbs/delete-single.ts" -->

Further Readings and Exercises

• Want to know more? Read/watch...
  • Microsoft's REST API Guidelines
  • restify documentation
• Exercises
  • CouchDB exercise
  • RSVP exercise