0Pricing
Clojure Functional Programming & JVM Backend Development · 课时

构建 RESTful API

从零开始构建完整的 RESTful API，涵盖身份验证、验证和数据序列化。

构建 RESTful API 是 CoddyKit 上的免费 Clojure Functional Programming & JVM Backend Development 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Clojure Functional Programming & JVM Backend Development 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Clojure Functional Programming & JVM Backend Development 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

What is a RESTful API?

A RESTful API (Representational State Transfer Application Programming Interface) is a standard way for computer systems to communicate over the web.

It uses standard HTTP methods (like GET, POST, PUT, DELETE) to perform actions on resources, which are specific pieces of data or functionality.

Key principles include:

  • Resources: Everything is a resource (e.g., a user, a product).
  • Statelessness: Each request from a client to server must contain all information needed to understand the request.
  • Uniform Interface: A consistent way to interact with resources.

Our Task Manager API Goal

For this lesson, we'll build a simple Task Manager API. This API will allow us to:

  • Create new tasks.
  • List all tasks.
  • Retrieve a specific task.
  • Update an existing task.
  • Delete a task.

We'll focus on handling JSON data, basic authentication, and input validation.

Setting Up Our Web Server

We'll use Ring for HTTP abstraction and Compojure for routing. Here's a basic setup for our API server. We'll define routes for our task resources.

The handler function will process requests, and run-jetty starts the server.

(ns coddykit.api
  (:require [compojure.core :refer [defroutes GET POST PUT DELETE]]
            [compojure.route :as route]
            [ring.adapter.jetty :refer [run-jetty]]
            [ring.middleware.json :refer [wrap-json-response]]
            [ring.middleware.json :refer [wrap-json-body]])
  (:gen-class))

(defonce tasks (atom {}))

(defn create-task [task-data]
  (let [id (str (java.util.UUID/randomUUID))
        new-task (assoc task-data :id id)]
    (swap! tasks assoc id new-task)
    new-task))

(defroutes app-routes
  (GET "/tasks" [] {:status 200 :body (vals @tasks)})
  (POST "/tasks" req
    (let [task-data (:body req)
          new-task (create-task task-data)]
      {:status 201 :body new-task}))
  (route/not-found "Not Found"))

(defn wrap-api-middleware [handler]
  (-> handler
      (wrap-json-response)
      (wrap-json-body {:keywords? true :bigdec-enable? true})))

(def app (wrap-api-middleware app-routes))

(defn -main [& args]
  (println "Starting server on port 3000...")
  (run-jetty app {:port 3000 :join? false}))

Parsing JSON Request Bodies

When clients send data to our API (e.g., for creating a new task), it's often in JSON format. We need to parse this JSON string into a Clojure map.

The ring.middleware.json/wrap-json-body middleware does this for us. It parses the request body and puts the resulting Clojure map into (:body req).

In the example, we added (wrap-json-body {:keywords? true}) to automatically convert JSON keys to Clojure keywords.

Constructing JSON Responses

Our API needs to send data back to clients, usually as JSON. This involves converting Clojure maps into JSON strings and setting the correct Content-Type header.

The ring.middleware.json/wrap-json-response middleware handles this. If your response :body is a Clojure map or vector, it automatically converts it to JSON and sets "Content-Type": "application/json".

Let's add a GET route for a single task.

(ns coddykit.api
  (:require [compojure.core :refer [defroutes GET POST PUT DELETE]]
            [compojure.route :as route]
            [ring.adapter.jetty :refer [run-jetty]]
            [ring.middleware.json :refer [wrap-json-response]]
            [ring.middleware.json :refer [wrap-json-body]])
  (:gen-class))

(defonce tasks (atom {}))

(defn create-task [task-data]
  (let [id (str (java.util.UUID/randomUUID))
        new-task (assoc task-data :id id)]
    (swap! tasks assoc id new-task)
    new-task))

(defroutes app-routes
  (GET "/tasks" [] {:status 200 :body (vals @tasks)})

  (GET "/tasks/:id" [id]
    (if-let [task (get @tasks id)]
      {:status 200 :body task}
      {:status 404 :body {:message "Task not found"}}))

  (POST "/tasks" req
    (let [task-data (:body req)
          new-task (create-task task-data)]
      {:status 201 :body new-task}))

  (route/not-found "Not Found"))

(defn wrap-api-middleware [handler]
  (-> handler
      (wrap-json-response)
      (wrap-json-body {:keywords? true :bigdec-enable? true})))

(def app (wrap-api-middleware app-routes))

(defn -main [& args]
  (println "Starting server on port 3000...")
  (run-jetty app {:port 3000 :join? false}))

Implementing Basic Authentication

Authentication verifies the identity of a client. For a simple API, we can use a token in the Authorization header.

We'll create a middleware function that checks for a specific API key. If it's missing or invalid, we return a 401 Unauthorized status.

This middleware wraps our main application routes, ensuring every request passes through it.

(ns coddykit.api
  (:require [compojure.core :refer [defroutes GET POST PUT DELETE]]
            [compojure.route :as route]
            [ring.adapter.jetty :refer [run-jetty]]
            [ring.middleware.json :refer [wrap-json-response]]
            [ring.middleware.json :refer [wrap-json-body]])
  (:gen-class))

(defonce tasks (atom {}))
(def api-key "my-secret-api-key") ; Example API key

(defn create-task [task-data]
  (let [id (str (java.util.UUID/randomUUID))
        new-task (assoc task-data :id id)]
    (swap! tasks assoc id new-task)
    new-task))

(defn authenticate [handler]
  (fn [request]
    (let [auth-header (get-in request [:headers "authorization"])
          [_ token] (re-matches #"Bearer (.*)" auth-header)]
      (if (= token api-key)
        (handler request)
        {:status 401 :body {:message "Unauthorized"}}))))

(defroutes app-routes
  (GET "/tasks" [] {:status 200 :body (vals @tasks)})

  (GET "/tasks/:id" [id]
    (if-let [task (get @tasks id)]
      {:status 200 :body task}
      {:status 404 :body {:message "Task not found"}}))

  (POST "/tasks" req
    (let [task-data (:body req)
          new-task (create-task task-data)]
      {:status 201 :body new-task}))

  (route/not-found "Not Found"))

(defn wrap-api-middleware [handler]
  (-> handler
      (authenticate) ; Apply authentication first
      (wrap-json-response)
      (wrap-json-body {:keywords? true :bigdec-enable? true})))

(def app (wrap-api-middleware app-routes))

(defn -main [& args]
  (println "Starting server on port 3000...")
  (run-jetty app {:port 3000 :join? false}))

Input Validation for Tasks

Validation ensures that the data received from clients is correct and complete before processing it. This prevents errors and maintains data integrity.

For our tasks, let's ensure that a :title and :description are always provided when creating or updating a task.

If validation fails, we'll return a 400 Bad Request with a helpful error message.

(ns coddykit.api
  (:require [compojure.core :refer [defroutes GET POST PUT DELETE]]
            [compojure.route :as route]
            [ring.adapter.jetty :refer [run-jetty]]
            [ring.middleware.json :refer [wrap-json-response]]
            [ring.middleware.json :refer [wrap-json-body]])
  (:gen-class))

(defonce tasks (atom {}))
(def api-key "my-secret-api-key")

(defn create-task [task-data]
  (let [id (str (java.util.UUID/randomUUID))
        new-task (assoc task-data :id id)]
    (swap! tasks assoc id new-task)
    new-task))

(defn authenticate [handler]
  (fn [request]
    (let [auth-header (get-in request [:headers "authorization"])
          [_ token] (re-matches #"Bearer (.*)" auth-header)]
      (if (= token api-key)
        (handler request)
        {:status 401 :body {:message "Unauthorized"}}))))

(defn validate-task [task]
  (cond
    (nil? (:title task)) {:valid false :error "Title is required"}
    (nil? (:description task)) {:valid false :error "Description is required"}
    :else {:valid true}))

(defroutes app-routes
  (GET "/tasks" [] {:status 200 :body (vals @tasks)})

  (GET "/tasks/:id" [id]
    (if-let [task (get @tasks id)]
      {:status 200 :body task}
      {:status 404 :body {:message "Task not found"}}))

  (POST "/tasks" req
    (let [task-data (:body req)
          validation (validate-task task-data)]
      (if (:valid validation)
        (let [new-task (create-task task-data)]
          {:status 201 :body new-task})
        {:status 400 :body {:message (:error validation)}})))

  (route/not-found "Not Found"))

(defn wrap-api-middleware [handler]
  (-> handler
      (authenticate)
      (wrap-json-response)
      (wrap-json-body {:keywords? true :bigdec-enable? true})))

(def app (wrap-api-middleware app-routes))

(defn -main [& args]
  (println "Starting server on port 3000...")
  (run-jetty app {:port 3000 :join? false}))

Updating & Deleting Resources

To complete our CRUD (Create, Read, Update, Delete) operations, we need PUT and DELETE routes. These typically operate on a specific resource identified by its ID.

A PUT request updates an existing task, while a DELETE request removes it from our tasks atom.

(ns coddykit.api
  (:require [compojure.core :refer [defroutes GET POST PUT DELETE]]
            [compojure.route :as route]
            [ring.adapter.jetty :refer [run-jetty]]
            [ring.middleware.json :refer [wrap-json-response]]
            [ring.middleware.json :refer [wrap-json-body]])
  (:gen-class))

(defonce tasks (atom {}))
(def api-key "my-secret-api-key")

(defn create-task [task-data]
  (let [id (str (java.util.UUID/randomUUID))
        new-task (assoc task-data :id id)]
    (swap! tasks assoc id new-task)
    new-task))

(defn authenticate [handler]
  (fn [request]
    (let [auth-header (get-in request [:headers "authorization"])
          [_ token] (re-matches #"Bearer (.*)" auth-header)]
      (if (= token api-key)
        (handler request)
        {:status 401 :body {:message "Unauthorized"}}))))

(defn validate-task [task]
  (cond
    (nil? (:title task)) {:valid false :error "Title is required"}
    (nil? (:description task)) {:valid false :error "Description is required"}
    :else {:valid true}))

(defroutes app-routes
  (GET "/tasks" [] {:status 200 :body (vals @tasks)})

  (GET "/tasks/:id" [id]
    (if-let [task (get @tasks id)]
      {:status 200 :body task}
      {:status 404 :body {:message "Task not found"}}))

  (POST "/tasks" req
    (let [task-data (:body req)
          validation (validate-task task-data)]
      (if (:valid validation)
        (let [new-task (create-task task-data)]
          {:status 201 :body new-task})
        {:status 400 :body {:message (:error validation)}})))

  (PUT "/tasks/:id" [id req]
    (let [updated-data (:body req)
          validation (validate-task updated-data)]
      (if (:valid validation)
        (if (get @tasks id)
          (do
            (swap! tasks update id merge updated-data)
            {:status 200 :body (get @tasks id)})
          {:status 404 :body {:message "Task not found"}})
        {:status 400 :body {:message (:error validation)}})))

  (DELETE "/tasks/:id" [id]
    (if (get @tasks id)
      (do
        (swap! tasks dissoc id)
        {:status 204 :body nil}) ; 204 No Content for successful deletion
      {:status 404 :body {:message "Task not found"}}))

  (route/not-found "Not Found"))

(defn wrap-api-middleware [handler]
  (-> handler
      (authenticate)
      (wrap-json-response)
      (wrap-json-body {:keywords? true :bigdec-enable? true})))

(def app (wrap-api-middleware app-routes))

(defn -main [& args]
  (println "Starting server on port 3000...")
  (run-jetty app {:port 3000 :join? false}))

Data Serialization for Output

Sometimes, the internal representation of your data might contain fields you don't want to expose directly in your API responses (e.g., internal IDs, passwords, timestamps).

Serialization is the process of transforming internal data structures into a suitable format for the API response. For example, we might want to ensure a :created-at timestamp is in a specific string format.

We can create helper functions to 'clean' or format data before it's sent as JSON.

(ns coddykit.api
  (:require [compojure.core :refer [defroutes GET POST PUT DELETE]]
            [compojure.route :as route]
            [ring.adapter.jetty :refer [run-jetty]]
            [ring.middleware.json :refer [wrap-json-response]]
            [ring.middleware.json :refer [wrap-json-body]])
  (:gen-class))

(defonce tasks (atom {}))
(def api-key "my-secret-api-key")

(defn create-task [task-data]
  (let [id (str (java.util.UUID/randomUUID))
        new-task (assoc task-data :id id :created-at (java.time.Instant/now))]
    (swap! tasks assoc id new-task)
    new-task))

(defn format-task-for-api [task]
  (-> task
      (update :created-at str) ; Convert Instant to string
      (dissoc :internal-field) ; Remove any internal fields
      ))

(defn authenticate [handler]
  (fn [request]
    (let [auth-header (get-in request [:headers "authorization"])
          [_ token] (re-matches #"Bearer (.*)" auth-header)]
      (if (= token api-key)
        (handler request)
        {:status 401 :body {:message "Unauthorized"}}))))

(defn validate-task [task]
  (cond
    (nil? (:title task)) {:valid false :error "Title is required"}
    (nil? (:description task)) {:valid false :error "Description is required"}
    :else {:valid true}))

(defroutes app-routes
  (GET "/tasks" [] {:status 200 :body (map format-task-for-api (vals @tasks))})

  (GET "/tasks/:id" [id]
    (if-let [task (get @tasks id)]
      {:status 200 :body (format-task-for-api task)}
      {:status 404 :body {:message "Task not found"}}))

  (POST "/tasks" req
    (let [task-data (:body req)
          validation (validate-task task-data)]
      (if (:valid validation)
        (let [new-task (create-task task-data)]
          {:status 201 :body (format-task-for-api new-task)})
        {:status 400 :body {:message (:error validation)}})))

  (PUT "/tasks/:id" [id req]
    (let [updated-data (:body req)
          validation (validate-task updated-data)]
      (if (:valid validation)
        (if (get @tasks id)
          (do
            (swap! tasks update id merge updated-data)
            {:status 200 :body (format-task-for-api (get @tasks id))})
          {:status 404 :body {:message "Task not found"}})
        {:status 400 :body {:message (:error validation)}})))

  (DELETE "/tasks/:id" [id]
    (if (get @tasks id)
      (do
        (swap! tasks dissoc id)
        {:status 204 :body nil})
      {:status 404 :body {:message "Task not found"}}))

  (route/not-found "Not Found"))

(defn wrap-api-middleware [handler]
  (-> handler
      (authenticate)
      (wrap-json-response)
      (wrap-json-body {:keywords? true :bigdec-enable? true})))

(def app (wrap-api-middleware app-routes))

(defn -main [& args]
  (println "Starting server on port 3000...")
  (run-jetty app {:port 3000 :join? false}))

Handling API Errors Gracefully

A well-behaved API should always provide clear error messages and appropriate HTTP status codes when things go wrong.

We've already seen 401 Unauthorized, 404 Not Found, and 400 Bad Request. For unexpected server issues, a 500 Internal Server Error is standard.

You can use a global error handling middleware or specific error responses within your route handlers.

API Building Quick Check

Consider the following Clojure handler function for an API endpoint:

(defn create-user-handler [request]
  (let [user-data (:body request)
        username (:username user-data)]
    (if (nil? username)
      {:status 400 :body {:message "Username is required"}}
      {:status 201 :body {:message (str "User " username " created!")}})))

If a client sends a POST request with an empty body (or non-JSON body that results in (:body request) being nil), what HTTP status code and body would be returned by this handler, assuming wrap-json-body and wrap-json-response middlewares are active?

Recap: Building RESTful APIs

In this lesson, you've learned the core concepts of building a RESTful API using Clojure, Ring, and Compojure.

  • We defined resources and mapped HTTP methods to actions.
  • You saw how to parse incoming JSON requests and generate JSON responses.
  • We implemented basic authentication using middleware.
  • You learned about input validation to ensure data integrity.
  • Finally, we touched upon data serialization and effective error handling.

These are fundamental building blocks for any robust backend system!

常见问题解答

「构建 RESTful API」课时是免费的吗？

是的 — 「构建 RESTful API」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Clojure Functional Programming & JVM Backend Development 课程的其余内容，请升级到 CoddyKit PRO。 Clojure Functional Programming & JVM Backend Development 课程共包含 4 节课。

「构建 RESTful API」这节课中我会学到什么？

从零开始构建完整的 RESTful API，涵盖身份验证、验证和数据序列化。 你通过在浏览器中直接运行的动手代码来练习 Clojure Functional Programming & JVM Backend Development，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Clojure Functional Programming & JVM Backend Development 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Clojure Functional Programming & JVM Backend Development 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。

「构建 RESTful API」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Clojure Functional Programming & JVM Backend Development 课中编写并运行代码吗？

能。每节 Clojure Functional Programming & JVM Backend Development 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 构建 RESTful API
  2. 事件驱动架构
  3. 系统设计与可扩展性模式
  4. 认证与授权
← 返回 Clojure Functional Programming & JVM Backend Development