14. HTTP with Ring

Overview

In this chapter, we will process requests and generate responses, route incoming requests and manipulate requests via middleware. We will also serve up responses using various content types including JavaScript Object Notation (JSON) and Extensible Data Notation (EDN), create a web application using Ring and Compojure, and serve static resources via HTTP.

By the end of this chapter, you will be able to expose CRUD operations via HTTP.

Introduction

In the last chapter, we built our application layer and interacted with it via the REPL. This works sufficiently well for a single user performing ad hoc interactions, but it does not scale. Indeed, we could imagine a scenario where a third party or even another of our own services wants to make use of the data stored in our database, perform calculations, and persist updates. This interaction would be programmatic and would, therefore, benefit from being exposed over HyperText Transfer Protocol (HTTP) or similar.

We can achieve this by exposing our application layer via a web service. A web service allows interaction with our application layer over a network (most typically the internet, although it could be over an intranet for private applications).

To build our web service, we'll need a web application library to build our API, a web server to serve it up over HTTP, and a routing library to route incoming requests to the appropriate handler. Clojure has...

HTTP, Web Servers, and REST

Before we dive into building a web service, let's cover the basics. HTTP is one of the primary protocols for communicating across the internet, particularly when working in a web browser. This protocol provides a contract for a client (typically a web browser) to communicate with a (web) server. In this example, the browser will construct a request containing a Uniform Resource Identifier (URI), which it will use to communicate to the server. The server will interpret the request, using the URI string to determine which resource the client is interested in retrieving/manipulating, then constructing a response containing information indicating that the request has completed, or containing a payload in the form of the response body.

Typically, when building a web service, we want to conform to the REpresentational State Transfer (REST) architecture. This architecture prescribes a set of operations we can choose to perform against a resource, allowing...

Static Files

In the early days of the internet, web servers were used to serve up static HTML pages and images. Although technology has progressed a great deal since then, serving up static resources is still very much a requirement of today's web servers.

Thinking back to our CSV file of tennis matches from Chapter 5, Many to One: Reducing, we may wish to make this available to download via our web service.

compojure.route, which we previously used to provide a not-found route, also provides a means of easily serving static files from a custom location on disk. compojure.route/files accepts a path where the files will be exposed as well as an options map where we can override the directory that our files are served from.

The following code would allow us to access any files located under the /home/<user>/packt-http/resources/ directory by browsing to our web server's /files/<filename> route:

(route/files "/files/" {:root "/home/<...

Summary

This chapter introduced us to HTTP, web servers, and the request-response interaction between a web server and a client. Multiple clients were introduced, including the most typical (the web browser) as well as curl and clj-http. We learned how a web server takes an incoming request and routes it according to key elements of the incoming request map, before constructing a response map, which is then presented to the requesting client.

We learned about middleware and how it intercepts our request and/or response map. We then used muuntaja to format the content we generated for the client, as well as to format incoming data from the client as JSON or EDN.

After considering the content of our database in the context of groups of related resources, we learned how to construct appropriate paths to address them using a REST architecture. This paved the way for integrating our existing application layers with a web service that would allow any web client to interact with them...