Let’s send a request which gets routed to our handler, which creates the response. Let’s examine this response in more detail, via curl.

The response should be something like following (note that headers may appear in a different order):

The first three response headers are added by our webserver, Aleph.

Next we have another date and a string known as the entity tag:

The Last-Modified header shows when the string Hello World! was created, which happens to be the last time the system was started (or reset). Java strings are immutable, so yada is able to deduce that the string’s creation date is also the last time it could have been modified.

The entity tag is computed from the value of the Hello World! itself. Unlike the Last-Modified value, it can survive a reset.

Both Last-Modified and ETag are used to support HTTP conditional requests and conflict detection when uploading new versions of a resource.

Next we have a header telling us the media-type of the string’s representation.

yada is able to determine that the media-type is text, but without more information it must default to text/plain. It can also tell us the charset, which defaults to the default charset of the JVM (almost always utf-8)

Since the Java platform can encode a string to a number of charsets, yada adds a Vary header to signal to the user-agent (and proxy caches in between) that the body can change if a request contained a different Accept-Charset header. Java installations support many different charsets, so yada does too.

Next we are given the length of the body.

This value is in bytes, regardless of the charset. It includes the newline.

Finally we see our response body.

In HTTP, a conditional request is one where a user-agent (like a browser) can ask a server for the state of the resource but only if a particular condition holds.

A common condition is whether the resource has been modified since a particular date, usually because the user-agent already has a copy of the resource’s state which it can use if possible. If the resource hasn’t been modified since this date, the server can tell the user-agent that there is no new version of the state.

We can test this by setting the If-Modified-Since header in the request.

Here’s how we might do this using the curl command.

Of course, nobody will have modified the resource since the year 2525, so we should get a 304 response, telling us we can use our cached copy:

Notice we also get the same Vary and ETag headers. These help any proxies between the user-agent and the service properly cache content, and if they would have been produced in a 200 response, then they must also be produced in a 304. (This is the kind of thing that yada takes care of for you, unlike most libraries).

The responses we have received back from our service all contain this curious header called Vary set to accept-charset. The server is telling us (and any proxies between us) that the representation might vary depending on the charset negotiated. Let’s see if we can get our "Hello World!" message returned in other charsets.

Let’s try getting the string in UTF16 by telling the server that’s the only charset we’ll accept:

This returns the following:

The "Hello World!" message is prepended with 2 bytes called the Byte Order Mark (BOM). The length of the string (including the newline) is 13 characters. Since each character here is 2 bytes, that makes 26. The additional of the BOM makes it 28, which is what our Content-Length header reports.

A BOM indicates the order that the 2 bytes are transmitted in. In 'big endian' form the most-significant byte is transmitted first. We can tell the service that we only want the big endian form with the following:

This will now produce the message without the BOM, because it is unnecessary. This means our Content-Length will be exactly 13 * 2 = 26.

If we were to use UTF-32, which defaults to big-endian, we’ll get a Content-Length of 13 * 4 = 52.

Note also that different representations generate different ETag values. The entity tag is a way of managing a cache of representations, not a cache of resources. Think of the ETag value as the key you could use in a key/value store that stored a cache of representations.

The negotiation of charsets may be considered by some to be unnecessary given the dominance of UTF-8. That is certainly true for today’s modern browsers. However, there are many other types of devices that are being connected to the internet (under the banner 'Internet of Things'). Many of these devices have very tight constraints on processing and memory which prevent them from supporting UTF-8. If we are building a web service, we may want to connect these devices to it in the future.

Let’s try to overwrite the string by using a PUT.

The response is as follows:

The response status is 405 Method Not Allowed, telling us that our request was unacceptable. There is also an Allow header, telling us which methods are allowed. One of these methods is OPTIONS, which we could have used to check whether PUT was available without actually attempting it.

The response should be:

Both the PUT and the OPTIONS response contain an Allow header which tells us that PUT isn’t possible. This makes sense, because we can’t mutate a Java string.

We could, however, wrap the Java string in a Clojure atom which could reference different Java strings at different times.

To demonstrate this, try the following with the identifier http://localhost:3000/hello-atom.

Let’s try a normal GET.

We can now make another OPTIONS request to see whether PUT is available, before trying it.

It is! So let’s try it.

And now let’s see if we’ve managed to change the state of the resource.

As long as someone else hasn’t sneaked in a different state between your PUT and subsequent GET, you should see the new state of the resource is "Hello Wonderful World!". Great!

But what if someone did manage to PUT their change ahead of yours? Their version would now be overwritten. That might not be what you wanted. To ensure we don’t override someone’s change, we could have set the If-Match header using the ETag value.

Let’s test this now, using the ETag value we got before we sent our PUT request.

We get a 412, which means a pre-condition failed. The pre-condition in question relates to our If-Match header value not matching the current value of the atom. This is a very useful result, because it means we can ensure that we don’t overwrite someone else’s data.

There was one more method indicated by the Allow header of our OPTIONS request, which was HEAD. Let’s try this now.

The response does not have a body, but tells us the headers we would get if we were to try a GET request.

Often, a resource’s state or behavior will depend on parameters in the request. Let’s say we want to pass a parameter to the resource, via a query parameter.

To show this, we’ll write some real code:

This declares a resource with a GET method, which responds with a plain-text message formed from the query parameter.

Let’s see this in action, but without a parameter:

Here we get a 400 response. This means we’ve done something wrong (we’ve forgotten to add the query parameter).

Now let’s add the query parameter to the URI:

This should now get the 200 response we wanted:

Great!

As well as query parameters, yada supports path parameters, request headers, form data, cookies and request bodies. You can have optional parameters, in fact, anything that can be expressed in Plumatic Schema, and yada will even coerce parameters to a range of types. For more details, see the parameters chapter.

Now we have seen how to build a single web resource, let’s see how to build a Swagger description from a collection of web resources.

In your editor, switch to src/edge/web_server.clj. This file defines the overall route structure which includes our routes for "Hello World!". This has been included twice, both at the root and under the /api path.

This second version uses the Clojure threading macro → which wraps the route structure with yada/swaggered and gives it a bidi tag (used for generating URIs, we’ll use this later).

The purpose of yada/swaggered is to augment the route structure given to it with a route to swagger.json, which responds with a Swagger description of the route structure in JSON. Since yada resources are data maps, this is a relatively simple data transformation of the route structure.

We can test the resource is available at its /api location with curl:

We can also query the Swagger description with curl:

This time we get a JSON body returned:

Notice we still get a Vary header telling us that multiple charsets are available. JSON bodies are available in UTF-16 and UTF-32. Compare this with Clojure’s EDN, which is specificed to be UTF-8 only. In fact, yada is happy to produce Swagger definitions in EDN too:

Note that this time we get no Vary header, since there are no charset alternatives.

It’s these little details that yada takes care of for you. There is no trickery involved, it’s simply the result of an almost obsessive focus on the relevant web standards. There is nothing special about strings, yada applies the same logic for anything else you ask it to handle. We’ll see more in the next chapter.

By the way, if you want to see the Swagger UI, browse to http://localhost:3000/swagger/?url=http://localhost:3000/api/swagger.json

This has been a long chapter, but we have only covered a simple "Hello World!" example.

You should now realise that implementing even a basic example that properly complies with the HTTP standard is a surprisingly tough undertaking. But this simple example demonstrated how a rich and functional HTTP resource can be created with a tiny amount of code, and none of the behaviour we have seen is hardcoded or contrived. We have only demonstrated a simple Java string, and yada includes similar support for many other basic types (atoms, Clojure collections, files, directories, Java resources…).

But the best thing is you can programmatically create your own resources and types to fit your particular requirements.

Without a library like yada we would need to read and understand hundreds of pages of the HTTP RFCs and spend a great deal of extra effort coding up its various aspects. Of course, nobody would bother doing that, but the consequence is that we miss out on the many architectural benefits of HTTP.

Rarely can client code make any assumptions that the HTTP API it is accessing complies with the text in the HTTP RFCs, and must therefore rely on detailed knowledge of how the API is written, either through documentation, Swagger definitions, close collaboration between development teams or some other means (trial-and-error). This is a problem because it causes rigidity between our systems.

By using yada, we are pushing the responsibility of implementing HTTP correctly away from the programmer and into a library.