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

Links

HTTP

  • HTTP is stateless, every request is completely independent
  • 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.

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>