Added REST API descriptions

_sidebar.md

@@ -27,8 +27,10 @@
   - [DOM Manipulation](/the-internet/dom-manipulation.md)
   - [Event Loop](/the-internet/event-loop.md)
   - [HTTP](/the-internet/http.md)
+    - [HTTP methods](/the-internet/http-methods.md)
   - [API](/the-internet/api.md)
     - [Fetch](/the-internet/fetch.md)
+    - [Designing API's](/the-internet/designing-apis.md)
 - [HTML & CSS](/html-css/README.md)
   - [HTML](/html-css/html.md)
   - [CSS](/html-css/css.md)

definitions/crud.md

@@ -0,0 +1,7 @@
+# CRUD
+
+CRUD is short for _Create_, _Read_, _Update_ and _Delete_: the four actions that any backend application should be able to handle, no matter what language the code is written in. The CRUD structure responds to the user's need to create new data, to be able to read (display in the user interface) it, to update old data and finally to delete it.
+
+The concept of CRUD is an important condition that each web application needs to fulfill. Why? **This is generally how users use applications**.
+
+Read the following article to learn about CRUD in practice, using Facebook as an [example](https://medium.com/@Adetona77/understanding-crud-using-facebook-as-the-study-case-part-1-c4183cdf617a)

the-internet/api.md

@@ -22,7 +22,7 @@ Have a look at this video by [Stas](https://github.com/Stasel) that explains the
 
 {% hyf-youtube src="https://www.youtube.com/watch?v=Dr6ww7vp0Kc" %}
 
-### Public/private APIs
+## Public/private APIs
 
 There are 2 different types of APIs: **public** and **private** APIs.
 
@@ -36,7 +36,7 @@ Keep this in mind: in the real world **programming is only a means to serving a
 
 - [The Business Impact of Private, Partner and Public APIs](https://www.youtube.com/watch?v=Bk50AYGvs-g)
 
-### Connecting with APIs
+## Connecting with APIs
 
 A big part of what applications do is **moving data from one place to another**. Let's say you are on the HackYourFuture website and feel like donating some money. First of all, that's very nice of you! You head out to the website and click on the donate button. You type in the amount and click on "donate". You'll notice you immediately get redirected to a different website, namely checkout.stripe.com. How did Stripe know how to do this?
 
@@ -82,7 +82,7 @@ xhr.onerror = function() {
 
 This way of making HTTP Requests is outdated (and not recommended to use), but it's good to be aware of it as you might still see it in old code bases.
 
-The newer way of making HTTP Requests involves using the `Fetch API`. You'll learn more about that next week!
+The newer way of making HTTP Requests involves using the `Fetch API`. You can read more about this in our [fetch](./fetch.md) section.
 
 For further study of how to make HTTP Requests, check out the following resources:
 
@@ -95,3 +95,5 @@ If you just can't get enough, here are some extra links that mentors/students ha
 - [APIs Are Like User Interfaces - Just With Different Users in Mind](https://www.programmableweb.com/news/apis-are-user-interfaces-just-different-users-mind/analysis/2015/12/03)
 - [What are APIs - series](https://www.youtube.com/watch?v=cpRcK4GS068&list=PLcgRuP1JhcBP8Kh0MC53GH_pxqfOhTVLa)
 - [APIs for Beginners](https://www.youtube.com/watch?v=GZvSYJDk-us)
+- [ELI5: What is an API?](https://dev.to/awwsmm/eli5-what-is-an-api-1dd2)
+- [Web APIs Explained By Selling Goods From Your Farm](https://blog.codeanalogies.com/2018/02/27/web-apis-explained-by-selling-goods-from-your-farm/)

the-internet/designing-apis.md

@@ -0,0 +1,74 @@
+# Designing API's
+
+In the general [API section](/api.md) we looked at API's from the frontend, but let's go a little deeper into what an API is and more specifically: how to actually design one. Let's first start by going over what an API is and introduce a new analogy:
+
+## Analogy
+Application Programming Interface (API) in its simplest form is the part of an application that allows users to make use of its functionality. However, instead of a beautiful-looking user interface, it's usually some kind of URL (which in this context is often called an `endpoint`).
+
+Whenever developers make some kind of software that they want others to use, they make sure it can be communicated with. That part is called the API. The developers usually also write instructions for how to best communicate with the API, this is called `API documentation`.
+
+A useful analogy is that of a restaurant.
+
+> As a _client_ when you go to the restaurant you are not allowed to go into the kitchen (server). However, you can talk to the waiter (API) who will pass on your request to the kitchen. The kitchen will use the things that it has such as ingredients, pans and pots, and the chef's talent to prepare your food. The waiter will bring you the food (response). Of course, to order anything you need to know what is available and thus you need a menu (documentation).
+
+## RESTful API's
+Building software is like building houses: architecture is everything. The design of each part is just as important as the utility of it. REST is a specific architectural style for web applications. It serves to organize code in **predictable** ways.
+
+### What is REST?
+REST stands for Representational State Transfer. This means that when a client request information about a resource, the server will _transfer_ to the client a _representation_ of the _state_ of the requested resource.
+
+If this seems very abstract to you, don't worry, REST is only a concept, an idea of how applications should be organized.
+
+The world of `REST` consists of two things: resources and operations (Creating, Reading, Updating, Deleting).
+
+A `resource` can be any object, real or imaginary. On Instagram for example, a resource can be a user, a photo or a hashtag. REST offers a way to expose information about its resources. For example, for Instagram, the state of a user (the resource), contains the user's name, the number of posts that user has on Instagram, how many followers they have, and more. Resources have names e.g. _users_, _photos_ and _hashtags_ and each object in resource has an identifier. For example, a _user_ has a username.
+
+REST also enables clients to take actions on those resources. We call these actions `CRUD` operations:
+
+- Creating new resources, such as videos/images/text files, etc.
+- Retrieving those files and reading them.
+- Updating the content of those files.
+- Deleting those files.
+
+The most important features of REST are:
+
+- An application has a `frontend` (client) and a `backend` (server). This is called [separation of concerns](https://medium.com/machine-words/separation-of-concerns-1d735b703a60): each section has its specific job to do. The frontend deals with presenting data in a user friendly way, the backend deals with all the logic and data manipulation
+- The server is `stateless`, which means that it doesn't store any data about a client session. Simply put, when you refresh the page you won't keep the data you requested before (unless it's saved in the browser or in a file on the server). Whenever a client sends a request to the server, each request from the 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. This makes it possible to handle requests from millions of users.
+- Server responses can be temporarily stored on the client (a browser) using a process called `caching`: storing files like images or webpages in the browser to load the next time you enter a website (instead of getting them from the server, which generally takes longer to do).
+- Client-server communication is done through `Hypertext Transfer Protocol`, which serves as the style (the how) of communication.
+
+It's important to know about REST because it teaches us how web applications are designed and holds us to a standard that makes development and usage predictable. However, don't worry if you don't know what any of this means just yet. It's good to be exposed to it, and understanding will come with experience.
+
+For more research, check the following resource:
+
+- [What is REST: a simple explanation for beginners](https://medium.com/extend/what-is-rest-a-simple-explanation-for-beginners-part-1-introduction-b4a072f8740f)
+
+### What is a RESTful API?
+A RESTful API is nothing more than an API that follows the REST architectural pattern.
+
+That means that the API exposes resources and allows clients to perform operations on those resources. When a client wants to request information on a resource it needs to say which resource it wants information on. This is passed as a Universal Resource Locator (URL) in the HTTP request. The client also needs to say what operation he is trying to perform. This is specified in the method of the HTTP request.
+
+Let's look at a concrete example. Picture a REST API for a library with a domain at `library.edu/`. The resources would be `books`, so the URL for the books resource would be `library.edu/books`. If a client, e.g the librarian, wants to get information on the books he needs to use the `GET` HTTP method. The server will respond with a list of book information such as title, author etc.
+
+Now imagine that the librarian wants to register/create a new book. He needs to specify the resource he wants to create using the same URL as before `library.edu/books` and use the `POST` method. The information about the book to be created such as title, author etc., is part of the request body.
+
+Next, let's think about how the librarian would update the information for a specific book. The resource is still books and the method is `PUT`, but how do they tell the server which specific book to update? This is where the resource identifiers come in.
+The library needs to maintain and provide identifiers for each object. The user uses this identifier in the URL e.g. `library.edu/books/TheWhiteCastle`. The identifier can be a number or text, it does not matter. The same url is also used to delete a book, just with the `DELETE` method.
+
+To summarize, here are the available operations and the corresponding URLs.
+
+| Operation                                    | URL                                | HTTP Method |
+| -------------------------------------------- | ---------------------------------- | ----------- |
+| Get all books                                | `library.edu/books`                | `GET`       |
+| Create a new book                            | `library.edu/books`                | `POST`      |
+| Update the information about a specific book | `library.edu/books/TheWhiteCastle` | `PUT`       |
+| Delete a specific book                       | `library.edu/books/TheWhiteCastle` | `DELETE`    |
+
+The URL in the example consists of a domain `library.edu` and a path `/books`. When writing APIs we are mostly concerned with the _path_. You might also hear the synonymous _endpoint_ or _route_. During this weeks homework you will implement this exact API and then you will learn how all the different things fit together.
+
+For more information check out the following resources:
+
+- [What is an API? In English, please](https://medium.freecodecamp.org/what-is-an-api-in-english-please-b880a3214a82)
+- [Examples of REST APIs](https://nordicapis.com/5-examples-of-apis-we-use-in-our-everyday-lives/)
+
+

the-internet/http-methods.md

@@ -0,0 +1,17 @@
+# HTTP Methods
+
+Like verbal communication, there's the _content_ (WHAT you are saying) and the _style_ (HOW you are saying it). HTTP refers to the \***\*style\*\*** of online communication. How you communicate over the web is done through specific HTTP methods (also called HTTP verbs), that describe what type of request is being made. The most important ones are:
+
+- **GET**. This type of request is only about getting data from the server. Whenever a user enters a new webpage, a GET request is sent to the server to get the required files to display that webpage. All other data in the website stays unaffected.
+- **POST**. This type of request allows the client to submit new data to the server. Generally speaking, its purpose is to store this new data into a database, or manipulate it and later return it to the client.
+- **PUT**. This type of request allows the client to update existing data, which is already present in the client. The data is edited and then send back to the server, similar to the POST request, but more semantic.
+- **DELETE**. This type of request tells the server to delete a particular set of data or resources.
+
+Why do you need to know all of this? HTTP is the foundation of how client-server interactions work on the web. It's important to have a universal policy that everyone holds on to, to have fast and effective online communication.
+
+Have a look at the following videos that explain the client-server interactions:
+
+{% hyf-youtube src="https://www.youtube.com/watch?v=eesqK59rhGA" %}
+
+{% hyf-youtube src="https://www.youtube.com/watch?v=RsQ1tFLwldY" %}
+

tools/postman.md

@@ -0,0 +1,21 @@
+# Postman
+
+When creating APIs it is important to test if they work as intended. The easiest way to do this is to send a request and check the API's response.
+
+Normally, you would send a request using the browser or the command line. But there's a tool we can use that's made especially for these testing purposes: 
+
+{% hyf-youtube src="https://www.youtube.com/watch?v=i1jU-kivApg" %}
+
+Postman offers an intuitive graphical user interface that will help us visualize API requests and the responses we get.
+
+You can install Postman by following [these steps](https://learning.getpostman.com/docs/postman/launching_postman/installation_and_updates).
+
+As you can see in the image below, when you enter a request in Postman and click the Send button, the server receives your request and returns a response that Postman then displays in the interface.
+
+![postman illustration](https://s3.amazonaws.com/postman-static-getpostman-com/postman-docs/anatomy-of-a-request.png)
+
+Watch the following video to learn about how to start sending your first requests with Postman:
+
+{% hyf-youtube src="https://www.youtube.com/watch?v=YKalL1rVDOE" %}
+
+If you just want to try postman out a bit, you can query any open API (you can search through some open ones [here](https://public-apis.io/), or you can use the following module [JSON Server](https://github.com/typicode/json-server). This NPM module starts a RESTful API without you having to write a single line of code.