Merge pull request #34 from LaunchCodeEducation/ch-20-rest

Ch 20 rest

.gitignore

@@ -1,3 +1,4 @@
 **/.DS_Store
 .vscode
 *.swp
+public/

content/appendices/_index.md

@@ -0,0 +1,19 @@
+---
+title: "Appendices"
+date: 2023-01-20T08:49:09-06:00
+draft: false
+weight: 100
+originalAuthor: <no value> # to be set by page creator
+originalAuthorGitHub: <no value> # to be set by page creator
+reviewer: # to be set by the page reviewer
+reviewerGitHub: # to be set by the page reviewer
+lastEditor: # update any time edits are made after review
+lastEditorGitHub: # update any time edits are made after review
+lastMod: # UPDATE ANY TIME CHANGES ARE MADE
+---
+
+
+
+## Content Links
+
+{{% children %}}

content/appendices/install-postman/_index.md

@@ -0,0 +1,57 @@
+---
+title: "Installing Postman"
+date: 2023-01-20T08:49:09-06:00
+draft: false
+weight: 75
+originalAuthor: John Woolbright # to be set by page creator
+originalAuthorGitHub: jwoolbright23 # to be set by page creator
+reviewer: Kimberly Horan # to be set by the page reviewer
+reviewerGitHub: codinglikeagirl42 # to be set by the page reviewer
+lastEditor: # update any time edits are made after review
+lastEditorGitHub: # update any time edits are made after review
+lastMod: 03/08/23 # UPDATE ANY TIME CHANGES ARE MADE
+---
+
+When exploring and testing a web API, it is invaluable to have an interactive environment that allows you to fine-tune requests. For example, you may need to configure the HTTP method, headers, or body of the request -- all of which the browser does not allow you to do. Instead of testing in a browser, we can use tools made specifically for interacting with APIs. One of the most popular API tools in the industry is **Postman**. Postman is a cross-platform tool that puts you in full control of configuring and executing API requests. 
+
+Installing Postman is easy thanks to its cross-platform nature. You can download the installer on [their downloads page](https://www.postman.com/downloads/). 
+
+## Mac Users
+
+1. Select the version that matches the type of chip your Mac has. If you are unsure if you have an Intel chip or the Apple chip, click on the apple in the upper left corner of your screen. Select **About This Mac**. Under *Processor* on the **Overview** tab, you will see the chip manufaturer.
+
+![Postman installation page with two Mac options displayed](pictures/download-installer-mac.png?classes=border)
+
+2. After installation, you can open the app. Postman will first prompt you to make an account, but if you are uncomfortable doing so, at the bottom of the screen is the option to sign up for an account later.
+
+The main view of Postman is the launchpad view.
+
+![Postman launchpad view for Mac, contains overview of initial actions a user can make with the software](pictures/launchpad-view-mac.png?classes=border)
+
+You are ready to go!
+
+## Windows Users
+
+1. Select the **Windows x64** installer download then run the installer:
+
+![Close up of webpage to install Postman, user selecting Windows x64 option](pictures/download-installer.png?classes=border)
+
+Windows user should select the *Windows 64-bit* download option
+
+2. After installation, if Postman does not open automatically, locate the download and open it manually. Making an account can be useful, but if you do not want to create one, select the link in grey at the bottom of the splash screen that reads: "Skip signing in and take me straight to the to the app":
+
+![Postman splash screen for a new account](pictures/account.png?classes=border)
+
+{{% notice blue "Note" "rocket" %}}
+**Windows Users**: Once installed, you can right-click the Postman icon and pin it to your taskbar for easy access in the future:
+
+![User pins the Postman application to their taskbar on Windows](pictures/pin-taskbar.png?classes=border)
+
+Pinning the Postman application to your Windows taskbar could make your life easier
+{{% /notice %}}
+
+3. You can leave the launchpad view open for now. We will explore Postman after setting up our API server.
+
+![Postman launchpad view, contains overview of initial actions a user can make with the software](pictures/launchpad-view.png?classes=border)
+
+Now that Postman is installed, there are a lot of features of the software to explore

content/assignments/techjobs-mvc/getting-started/_index.md

@@ -163,14 +163,14 @@ the link text.
 
 The most interesting part of this template is how we generate the links:
 
-```html {linenos=table}
-<td th:each="category : ${tableChoices}">
-   <ul>
-      <li th:each="item : ${category.value}">
-         <a th:href="@{/list/jobs(column=${category.key},value=${item})}" th:text="${item}"></a>
-      </li>
-   </ul>
-</td>
+```html {linenos=true}
+   <td th:each="category : ${tableChoices}">
+      <ul>
+         <li th:each="item : ${category.value}">
+            <a th:href="@{/list/jobs(column=${category.key},value=${item})}" th:text="${item}"></a>
+         </li>
+      </ul>
+   </td>
 ```
 
 1. `tableChoices` is a HashMap from `JobData`, and it contains the names of

content/web-api-rest/_index.md

@@ -0,0 +1,58 @@
+---
+title: "Chapter 20: Introduction to Web APIs & REST"
+date: 2021-10-01T09:28:27-05:00
+draft: false
+weight: 20
+originalAuthor: John Woolbright # to be set by page creator
+originalAuthorGitHub: jwoolbright23 # to be set by page creator
+reviewer: Sally Steuterman # to be set by the page reviewer
+reviewerGitHub: gildedgardenia # to be set by the page reviewer
+lastEditor: # update any time edits are made after review
+lastEditorGitHub: # update any time edits are made after review
+lastMod: # UPDATE ANY TIME CHANGES ARE MADE
+---
+
+## Learning Objectives
+
+After completing this chapter, you should be able to do the following:
+1. Submit HTTP requests using `Postman` to an API and receive the expected response
+- `GET`
+- `POST`
+- `DELETE`
+2. Submit a bad HTTP reuqest, understand the response and how to fix it
+
+You should also have an understanding of the following:
+1. HTTP methods
+1. Endpoints
+1. Status Codes
+1. Headers
+1. API design
+
+## Key Terminology
+
+### Web APIs
+1. API
+1. Web API
+1. Server-side rendering
+1. Client-side rendering
+1. data presentation
+1. data representation
+1. state
+
+### What is REST
+1. REST
+1. RESTful web services
+1. Representational state transfer
+1. JSON serialization
+1. JASON deserialization
+1. resource
+1. resource entity
+1. resource collection
+
+### REST: Practical Fundamentals
+1. Shape
+1. Endpoint
+
+## Content Links
+
+{{% children %}}

content/web-api-rest/exercises/_index.md

@@ -0,0 +1,200 @@
+---
+title: "Exercises: Web APIs and REST"
+date: 2021-10-01T09:28:27-05:00
+draft: false
+weight: 2
+originalAuthor: John Woolbright # to be set by page creator
+originalAuthorGitHub: jwoolbright23 # to be set by page creator
+reviewer: Sally Steuterman # to be set by the page reviewer
+reviewerGitHub: gildedgardenia # to be set by the page reviewer
+lastEditor: # update any time edits are made after review
+lastEditorGitHub: # update any time edits are made after review
+lastMod: # UPDATE ANY TIME CHANGES ARE MADE
+---
+
+We've created a basic API application [here](https://github.com/LaunchCodeEducation/events-api). Before we ask you to fork and clone this, let's first think conceptually about the kinds of requests a client application could make to this API.
+
+## The API
+
+The api starts by only exposing a single resource, `Event`, and four endpoints for interacting with it.
+
+### The Resource
+
+The shape of the `Event` resource describes the general form of its properties and value types:
+
+```bash {linenos=table}
+Event {
+   id: integer
+   name: string
+   description: string
+}
+```
+
+
+In our case, the `Event` shape is just the properties and types (translated to portable [JSON types](https://json-schema.org/understanding-json-schema/reference/type.html) defined in a `Event` model class.
+
+```java {linenos=table}
+public class Event {
+   public int id;
+   public string name;
+   public string description;
+
+...getters
+
+...setters
+}
+```
+
+An example of a real `Event` JSON response to a `GET` request would look like this:
+
+```bash {linenos=table}
+{
+   "id": 1,
+   "name": "LaunchCode API demo",
+   "description": "Learn how to use Postman to interact with an API!"
+}
+```
+
+Notice how this JSON is just a representation of an instance of the `Event` model class. The data shape has been converted from a Java object representation to a JSON string representation so it can be transported over HTTP. Recall that we perform this 
+conversion, or serialization, so that our API can output data in a portable format that is language-agnostic.
+
+### The Endpoints
+
+This branch of the API has four endpoints: 
+
+1. [GET Coding Events](#get-coding-events)
+1. [GET a Single Coding Event](#get-a-single-coding-event)
+1. [Create a Coding Event](#create-a-coding-event)
+1. [Delete a Coding Event](#delete-a-coding-event)
+
+#### Get Coding Events
+
+We'll ask you to consider some details of how to describe these endpoints.
+
+Remember, an endpoint is made up of a path (to the resource) and a method (action to take on the 
+resource). Because we only have one resource, each of our endpoints share a common entry-point path of `/events`. Request and response bodies are all in JSON, or more specifically, they have a `Content-Type` header value of `application/json`.
+
+Making a `GET` request to the entry-point of a resource should return a representation of the state of the collection. In our case, this representation is a JSON array with `Event` elements:
+
+```bash
+[
+   Event { ... },
+   ...
+]
+```
+
+If the current state of the collection is empty, then we will just get back an empty JSON array:
+
+```bash {linenos=table}
+   []
+```
+
+{{% notice green "Question" "rocket" %}}
+Using our endpoint shorthand, how would we describe this action?
+
+Some items to consider:
+
+1. What is the HTTP request type being used?
+1. What is the resource path being requested?
+1. Is there a request body being sent? What is included in it?
+1. If the request is successful, what information can we expect to be included in the response?
+{{% /notice %}}
+
+#### GET a Single Coding Event
+
+If you want to view the representation of a single entity, you need to provide information to uniquely identify it in the collection. Since the entry-point represents the collection, it can be followed by an `id` value in the path to look inside the collection and return just the corresponding entity.
+
+When describing entity endpoints, we use a path variable notation, `{variableName}`, to symbolize where the value needs to be put in the path. 
+
+If an entity with the given `id` is found, we will get a single `Event` JSON object back. If it is not found, we will receive a response with a `404` status code to indicate the failed lookup.
+
+{{% notice green "Question" "rocket" %}}
+Using our endpoint shorthand, how would we describe this action?
+
+Some items to consider:
+
+1. What is the HTTP request type being used?
+1. What is the resource path being requested?
+1. Is there a request body being sent? What is included in it?
+1. If the request is successful, what information can we expect to be included in the response?
+1. If the request contains an error, what information can we expect to be included in the response?
+{{% /notice %}}
+
+#### Create a Coding Event
+
+Think about what it means to create an entity. You need to provide the required data and the collection it belongs to. When we want to create an `Event`, we are asking the API to change the state of the collection (the list of entities) so our path must be `/events`. Recall that the "C" in CRUD stands for "create". Putting the resource and the action together, we know we 
+need to `POST` to the `/events` endpoint. Finally, as part of our request, we will need to send a request body containing the data required to create the entity.
+
+The shape of the `NewEvent` describes the JSON body that the endpoint expects:
+
+```bash
+NewCodingEvent {
+   name: string
+   description: string
+}
+```
+
+When making a request, you would need to send a JSON body like this to satisfy the general shape:
+
+```bash
+{
+   "name": "Halloween Hackathon!",
+   "description": "A gathering of nerdy ghouls to work on GitHub Hacktoberfest contributions"
+}
+```
+
+{{% notice blue "Note" "rocket" %}}
+We only provide the user editable fields, not the unique `id` which the API handles internally when saving to the database.
+{{% /notice %}}
+
+Recall that when a `POST` request is successful, the API should respond with the `201`, or *Created*, HTTP status code. As part of the `2XX` HTTP success status codes, it indicates a particular type of successful response with a special header.
+
+One of the REST conventions states that when an entity is created, the response should include both this status and the `Location` header that provides the URL of the new entity:
+
+```bash
+Location=<server origin>/events/<new entity id>
+```
+
+As an example:
+
+```bash {linenos=table}
+Location=http://localhost:8080/events/1
+```
+
+You can then issue a `GET` request to the `Location` header value and view the new entity. 
+
+If the request fails because of a client error, then it will respond with a `400` status code and a message about what went wrong.
+ 
+{{% notice green "Question" "rocket" %}}
+Using our endpoint shorthand, how would we describe this action?
+
+Some items to consider:
+
+1. What is the HTTP request type being used?
+1. What is the resource path being requested?
+1. Is there a request body being sent? What is included in it?
+1. If the request is successful, what information can we expect to be included in the response?
+1. If the request contains an error, what information can we expect to be included in the response?
+{{% /notice %}}
+
+#### Delete a Coding Event
+
+Deleting a `Event` resource is an operation on a single entity. Just like the endpoint for getting a single entity, this endpoint requires a `id` path variable. When a resource is deleted, a RESTful API should respond with a `204` status code. Similar to the `201` status, this code indicates a success with no response body or special headers. 
+
+If you attempt to delete a resource that doesn't exist (with an incorrect `id`), then the endpoint will respond with an expected `404` status and message.
+
+{{% notice green "Question" "rocket" %}}
+Using our endpoint shorthand, how would we describe this action?
+
+Some items to consider:
+
+1. What is the HTTP request type being used?
+1. What is the resource path being requested?
+1. Is there a request body being sent? What is included in it?
+1. If the request is successful, what information can we expect to be included in the response?
+1. If the request contains an error, what information can we expect to be included in the response?
+{{% /notice %}}
+
+### Install Postman
+Now that we've explored working with those endpoints, we're almost ready to start running the API and test sending those requests. 
+You'll need to [install Postman]({{< relref "../../../appendices/install-postman/_index.md" >}}) to work with this lesson's studio and practice running these requests.

content/web-api-rest/next-steps/_index.md

@@ -0,0 +1,30 @@
+---
+title: "Next Steps"
+date: 2021-10-01T09:28:27-05:00
+draft: false
+weight: 4
+originalAuthor: John Woolbright # to be set by page creator
+originalAuthorGitHub: jwoolbright23 # to be set by page creator
+reviewer: Sally Steuterman # to be set by the page reviewer
+reviewerGitHub: gildedgardenia # to be set by the page reviewer
+lastEditor: # update any time edits are made after review
+lastEditorGitHub: # update any time edits are made after review
+lastMod: # UPDATE ANY TIME CHANGES ARE MADE
+---
+
+We have covered the fundamentals aspects of the RESTful mental model and practical usage. However, RESTful design is a deep topic that even extends beyond the web and use of HTTP!
+
+If you want to learn more, the following links are a good start:
+
+#### Practical Understanding
+
+- [Craig Dennis: APIs for beginners (YouTube)](https://www.youtube.com/watch?v=GZvSYJDk-us&t=0s)
+- [REST sub-collections, relationships and links](https://restful-api-design.readthedocs.io/en/latest/relationships.html)
+- [OpenAPI specification and Swagger REST tools](https://swagger.io/specification/)
+- [The GitHub API](https://developer.github.com/v3/) and [Stripe (payment processing) API](https://stripe.com/docs/api) are excellent examples of RESTful design (and fantastic documentation)
+
+#### Deep Understanding
+
+- [the REST constraints](https://www.restapitutorial.com/lessons/whatisrest.html)
+- [The Richardson REST maturity model](https://www.martinfowler.com/articles/richardsonMaturityModel.html)
+- [the original REST doctoral thesis by Roy Fielding](https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)