import { addBanner, addArticle, addTitle, addHeader, addParagraph, addClassParagraph, addCaption, addSubHeader, addOrderedList, addUnorderedList, addBlockquote, addQuote, addInset, addInsetList, addInsetCodeListing, addInsetBulletList, addImageWithCaption, addButtonGroup, addSidebar, addSyntax, menu, global_menu } from '/scripts/import.js';
import { local_menu } from '/scripts/webdev.js';
const heading = document.querySelector(".heading");
const global = document.querySelector(".global_menu");
const local = document.querySelector(".local_menu");
const sidebar = document.querySelector(".sidebar");
const main = document.querySelector(".main_content");
heading.append(addTitle("Learning REST APIs"));
heading.append(addParagraph("Morten Rand-Hendriksen - LinkedIn Learning - February 2018"));
heading.append(addParagraph("Chapter 3 - Response"));
main.append(addHeader("Response Header"));
main.append(addParagraph("Every time a request is sent, a response is sent back and this includes a head section which contains, amongst other things, a response status code which we will look at in the next section. THe contents of the head section are partly determined by the type of request that is being sent or to be more specific, the HTTP method used to send the request."));
main.append(addParagraph("If you only want to see the head, you can send a HEAD request to any resource and an example of this along with a typical response is shown in figure 12."));
main.append(addImageWithCaption("./images/head.png", "Figure 12 - a HEAD request and a typical response."));
main.append(addParagraph("Note that the headers tell us what type of protocol was userd to service the request, in this case it is HTTP 1.1 and the HTTP resonse status which is 200 in this example. Additional meta data provides details on the server type, content type, the date and time when the response was sent and you may see other details popping up in these headers."));
main.append(addParagraph("As a matter of interest, I introduced a typo into the request and sent it again to see what sort of response we would get for a failed request and the result is shown in figure 13."));
main.append(addImageWithCaption("./images/head1.png", "Figure 13 - a HEAD request and a typical response with an invalid URL."));
main.append(addParagraph("As you can see, this time we are seeing a 404 response because the URL points to a location that does not exist and this is also what would happen if you mistyped a web address. For example, the URL for this page includes the name of the HTML document which is"));
main.append(addSyntax("response.html"));
main.append(addParagraph("If we change that to responses.html, we will see the response as shown in figure 14"));
main.append(addImageWithCaption("./images/head1.png", "Figure 14 - The response seen with an incorrect URL in the browsers address bar."));
main.append(addParagraph("Notice that the 404 message is not displayed in the browser window which is due to the fact that the web server has not been configured to display the message in that way but we can see that there is a 404 response shown under the Network tab in the browser's developer tools. Nowadays, web servers are often configured to show something other than a straightforward 404 response in order to help the user better determine the problem."));
main.append(addParagraph("That's a little bit of a digression. Arguably, the most important parts of the HEAD response are the status code which tells the client whether the request was successful or not and provides a good idea of why that specific response was sent and the content-type. For example, the content-type might specifiy json and so the client will know how to parse the data that it receieves or it might spcifit gzipped which tells the client that it has to use gzip to upack the data before it can be parsed."));
main.append(addParagraph("In part, the information that is included in the response headers will depend on the complexity of the API and the dataset that it manages, so be aware that you may see different things amongst these headers."));
main.append(addHeader("HTTP Status Messages"));
main.append(addParagraph("HTTP status messages are categorised as follows:"));
main.append(addInsetBulletList(["100 - Information.", "200 - Success", "300 - Redirection", "400 - Client error", "500 - Server error"]));
main.append(addParagraph("Let's look at each of these in a little more detail."));
main.append(addSubHeader("100 - Information"));
main.append(addParagraph("100 status codes are used to convey information only and are not commonly seen. They are used to inform the client of the status of the server, for example that it is busy, it is processing the clients' request or it is open and ready to accept the request."));
main.append(addSubHeader("200 - Success"));
main.append(addParagraph("Success responses sre most frequently used to indicate that the request completed successfully (usually, this is used to indicate that a GET request has been received and the required data has been sent to the client). In addition, a success response can indicate that some resource has been added to or created on the server or that a request has been completed successfully but did not return any content."));
main.append(addSubHeader("300 - Redirection"));
main.append(addParagraph("These are used to inform the client that the resource has been moved, either temporarily or permanently and it provides the new URL or URI that the client must use. There are a lot of variations on this type of response which can be quite confusing so it is important for an API builder to ensure that the correct response is sent."));
main.append(addSubHeader("400 - Client Error"));
main.append(addParagraph("These are used to indicate an error with the request as it is sent. This might be because the request is bad (it might be too large or contain some malformed JSON), the sender lacks the proper authorisation for the request being sent, the resource is not found (this is the 404 response that most people who use the web will have seen at some point) or that the client is using a method that is not permitted, for example, it is using a POST request on a resource that can only receive GET requests."));
main.append(addSubHeader("500 - Server Error"));
main.append(addParagraph("Typical server errors include an internal server error indicating that something has gone wrong on the server or some service on it has failed. You may also see an error if some service is temporarily unavailable. If the server is acting as a proxy or a gateway and the server it is trying to connect to is down, you may get a bad gateway error. It is important to remeber that an error can be with the server you are connecting to directly or it can be with a server you are connecting to indirectly."));
main.append(addParagraph("A fulllist of responses can be found in the MDN web docs under HTTP response status codes or you can download a list in pdf format from cheat-sheets.org."));
main.append(addHeader("REST and Authorization/Authentication"));
main.append(addParagraph("The methods that you can use in respect of a given resource depends on a number of factors, not least of which is the level of authorisation you have. For example, an API might allow read access for all users, POST access for some users and access to other methods such as PUT or PATCH to a relatively small number of users."));
main.append(addParagraph("If you send a request using HEAD, this will show you the methods allowed so you might see that GET is the only method permitted if you send that request without any form of authentication. However, if you send the same request with a set of valid credentials, you may see that the allowed methods include POST, PUT, PATCH and DELETE."));
main.append(addParagraph("In addition to the methods you are allowed to use, the headers returned when you send an authenticated request may inclide some additional data relating to the authorised session such as an expiry date and time, time to live and so on."));
addSidebar("webdev");