An Example
Background ↟
This project started as a resources for engineers who were learning Clojure during Hack Day events at work. For those who were new to Clojure, we wanted to offer an example project that provided insight on ways one can do the following:
- Define functions that comprise the REST server
- Define routes that call the REST API functions (separating HTTP-spefific code from "business logic" code)
- Configuration, logging, and database components
- Have functions that access a data source
- Provide a client library for the REST API
- Provide executable scripts that use the client library
- Include unit tests, functional tests, and style checking/linting
- Provide a means of running code in development mode locally
- Provide standalone .jar files for deplopyment into production
Since then, this has become a resource for seasoned devs whose Clojure REST chops are a bit rusty, and just need to get a jump-start for a new REST project.
About ↟
I'm New! ↟
What should I look at first, if I'm a new Clojure web developer?
Well, you should definitely ready the rest of this README. Then you might want to check out the following, probably in order:
src/example-rest/server/routes.clj
src/example-rest/server/api.clj
src/example-rest/client/core.clj
scripts/get-hello
Anatomy ↟
... Of this REST Project
Layout ↟
TBD
Server ↟
TBD
Client ↟
TBD
CLI ↟
[This section is showing all of its three years of age ... updates pending]
Creating Project Tools ...
It's always nice to deliver an API that already has at least one client library
available, so that users are not forced to resort to curl
and all the crazy,
long command line arguments that come with that. With an API defined, creating
a client library is very easy to do.
The next step in creating a good experience for your future users is to create
some tools based upon your client libraries. In particular, command line tools
are an excellent step in that direction. The scripts
directory gives some
examples of this, making use of the lein-exec
plugin. Another option would be
to create standalone jar files for each of your scripts. That entails more work
up front, but results in faster load times of the executable.
The example scripts provide command line arguments and options parsring:
$ ./scripts/get-hello -h
Switches Default Desc
-------- ------- ----
-h, --no-help, --help false Show Help
-b, --base-url http://localhost:8080 Base URL of the REST API server
Development ↟
From the command line:
TBD
From the REPL:
TBD
Testing ↟
Libraries used:
- clojure.test
- lein-kibit
- eastwood
Deployment ↟
The Makefile
gives an example of doing standalone deployment with the
standalone
target:
$ java -jar target/example-rest-api-0.1.0-SNAPSHOT-standalone.jar
That .jar
file is built with the following command:
$ make build
Which, in turn, calls the following to build the standalone .jar
file:
$ lein compile
$ lein uberjar
License ↟
Copyright © 2013-2016 Duncan McGreggor
Distributed under the Apache License Version 2.0.