REST API & HTTP - robbiehume/CS-Notes GitHub Wiki

Links

• What is a REST API?
• Web Server Concepts and Example
• HTTP Requests quick guide (Codecademy)
• REST API quick guide (Codecademy)
• https://github.com/robbiehume/CS-Notes/wiki/Web-Apps-&-Servers

---

HTTP

• HTTP is stateless, each request is completely independent
  • Doesn't mean there's no state at all, just that it's usually stored on the client side
  • The server never relies on information from previous requests
• Can think of HTTP as the "language" that the web server and web client use to communicate
• HTTP is just based on human-readable text
• HTTP is an application layer protocol
• HTTP responses aren't just web pages, in can also include:
  • JavaScript, JSON, images, video chunks, etc.

Stateless web apps:

• Stateful vs Stateless Web App Design
• Leonard Richardson and Sam Ruby described stateless systems best when they wrote, “Statelessness means that every HTTP request happens in complete isolation. When the client makes an HTTP request, it includes all information necessary for the server to fulfill that request. The server never relies on information from previous requests. If that information was important, the client would have sent it again in this request.”
• As for the REST APIs used in scalable web applications, Fielding describes a “stateless constraint” that says: “Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.”

HTTP Methods:

• GET: retrieve data from a specified resource
• POST: submit data to be processed to a specific resource
• PUT: update a specified resource
• DELETE: delete a specified resource
• Examples:
  • GET https://mysite.com/api/users
  • GET https://mysite.com/api/users/1 OR https://mysite.com/api/users/details/1
  • POST https://mysite.com/api/users
  • PUT https://mysite.com/api/users/1 OR https://mysite.com/api/users/update/1
  • DELETE https://mysite.com/api/users/1 OR https://mysite.com/api/users/delete/1

HTTP Status Codes

• 1xx - Informational: request received / processing
• 2xx - Success: successfully received, understood, and accepted
  • 200 - OK
  • 201 - OK created
• 3xx - Redirect: further action must be taken / redirect
  • 301 - Moved to new URL
  • 304 - Not modified (Cached version)
• 4xx - Client Error: request does not have what it needs
  • 400 - Bad request
  • 401 - Unauthorized
  • 404 - Not found
• 5xx - Server Error: server failed to fulfill an apparent valid request
  • 500 - Internal server error

HTTP Authentication header request:

• WWW-Authenticate header: link
• Sending the header will prompt the browser for a user name and password and then that authentication with each request

REST API

REST (Representational State Transfer): architecture style for designing networked applications

• Relies on stateless, client-server protocol, usually HTTP
• Treats objects on server-side as resources that can be created or destroyed
  • Resources are the core building blocks of RESTful systems
  • A resource can be a web page, video stream, image, etc.
• Usually returns JSON data
• All operations in a RESTful system should be stateless; each request is independent from each other

** HTTP is a RESTful protocol, but REST and HTTP are not the same thing

API (Application programming interface): contract provided by one piece of software to another

• Structured request and response
• Is a way for two separate pieces of software to communicate with each other
• Usually done over the web (web service / REST API), but can also be done locally
• API vs Web Service

REST API Benefits

• Simple / standardized
• Scalable / stateless
• High performance, mostly due to caching

Authentication:

• Some APIs require authentication to use their service
• Can be done with OAUTH token
• Authentication can be in the head or passed as a URL parameter

Postman is a nice app used to test requests / responses

CGI / FastCGI

• Set of standards that define how info is exchanged between the web server and a custom script
• Put script in /var/www/cgi-bin
• Must add carriage return and new line to end of each HTTP header line ('\r\n'; '\r\n\r\n' after last header line)
• FastCGI is very similar to CGI, but instead of spinning up a new process for each web request, while FastCGI has long running processes
  • This allows for higher efficiency and speed because you don't have to wait for the process to start up
  • The downside though is that you have to define each endpoint in the config file ahead of time
• It's best to start with CGI and only switch to FastCGI if you run into performance issues

curl

• curl is useful for testing API endpoints without having to use a web interface
• GET command: curl <url endpoint>
• Specify the HTTP request type (-X or --request): curl -X DELETE <url endpoint> or curl --request DELETE <url endpoint>
• Add data to the request body (-d or --data): curl -X PUT -d "username=Robbie" http://sample-api.com/users/1
  • If -d is used and no method is specified, it defaults to PUT
• Setting a header (-H or --header):
  • Set request content type: curl -d "{ \"username\": \"Lily\" }" -H "Content-Type: application/json" http://sample-api.com/users
  • The curl default content-type for POST/PUT requests is application/x-www-form-urlencoded
• View server response headers (-i or --include): curl -i <url endpoint>