Create a REST API Layer#

Since our GUI is going to run in the browser, we need something for the browser

to talk to. There are other choices we could make, but REST is the most sensible

choice we can make for this app in 2019. So that's what we're going to do!

Rocket is a web framework for Rust that will make it easy

for us to quickly write a Rust program to serve our API.

 Add Rocket to Cargo.toml#

We need to add Rocket to our app. Make your Cargo.toml's dependencies section

look like:

{{#include ../ch7-mytodo/Cargo.toml:dependencies}}
Copy

Run cargo build to download and compile all the new dependencies.

 Create the Backend Binary#

We'll write our backend in src/bin/backend.rs. Let's make a first rough pass:

{{#include ../ch7-mytodo/src/bin/backend-stub.rs}}
Copy

The first line enables a couple of features that Rocket's macros need. These are

experimental features, and this is part of why we need to build with Rust

nightly instead of stable.

Then we pull in Rocket's macros.

Then we've got the handler for our route. For the moment it just returns a

static string.

In our main we create a Rocket instance, mount our handler, and start it.

Now if you cargo run --bin backend it will compile everything and start our

backend listening on localhost port 8000. If you open your browser to

localhost:8000/tasks (or use curl) you will see "this is a response".

 Query the Database#

So far we've got a pretty lame API. It just spits out a static string. It's cool

that we can create a functioning web server from so little code, but we want to

return dynamic data -- info pulled from the database.

We've basically already written this code -- it's nearly the same as the

subcommand in our CLI program:

{{#include ../ch7-mytodo/src/bin/backend.rs:tasks_get}}
Copy

Run this (cargo will rebuild the changes for you), and refresh your browser --

you should see the task titles we inserted earlier. Great! But also, not so

great -- we might want to add more data to the tasks in the future as our app

gets popular. Like done-ness, due dates, and priority.

Just printing a bunch of lines of output is going to be tedious and error-prone

for our frontend to parse.

We can make it easier for our frontend and our backend to communicate

with each other if we use a standard data serialization format for our API, and

likewise if we use some standard tools to do it.

That format will be JSON. There are lots of tools for dealing with JSON, and

luckily for us one of them is part of Rocket. The other tool we need is the

excellent serde framework for serializing and

deserializing data (in JSON and many other formats).

 Serializing to JSON#

We need to add serde and JSON support from rocket_contrib to our

Cargo.toml:

{{#include ../ch7a-mytodo/Cargo.toml}}
Copy

And then we need to use rocket_contrib and serde in backend.rs:

{{#include ../ch7a-mytodo/src/bin/backend.rs:use}}
Copy

Let's think about how we want to format our response. We could just send back an

array of tasks, where each task is an object with a title key that has a

string value:

[

    { "title": "do the thing" },

    { "title": "get stuff done" }

]
Copy

One problem with this is that we have no uniform way to indicate an error. We'll

be better off if we're closer to complying with the [JSON API

spec](jsonapi.org), which requires an object at the top level, and a

data key at that level -- something like this:

{

    "data": [

        { "id": 1, "title": "do the thing" },

        { "id": 2, "title": "get stuff done" },

    ]

}
Copy

Note that this isn't strictly conforming with the JSON API spec because the

resource objects (the stuff in the data array) aren't formatted properly. But

for the sake of keeping this exposition simple we're going to settle for being

non-compliant for now -- see the exercises for an approach to getting this done

the right way.

Now that we know what we want to return, let's put together a Rust structure to

represent it in backend.rs:

{{#include ../ch7a-mytodo/src/bin/backend.rs:response}}
Copy

Here we're using the Serialize derive-macro from serde for our struct. This

makes it so that we can magically get JSON out of it. However, if we try to

build this we get an error:

error[E0277]: the trait bound `mytodo::db::models::Task: serde::ser::Serialize`

    is not satisfied
Copy

We can only Serialize a struct if all the things in the struct also implement

Serialize -- and Task doesn't do that... yet.

Can we fix it? YES WE CAN!

At the top of both lib.rs and backend.rs we need to enable serde macros:

{{#include ../ch7a-mytodo/src/lib.rs:serde}}
Copy

And then in db/models.rs we need to slap a Serialize on the Task struct:

{{#include ../ch7a-mytodo/src/db/models.rs:Task}}
Copy

Our handler function will use the Json type from rocket_contrib -- note

that this is a different type than serde's Json type! We need to add a use

declaration for it at the top of backend.rs:

{{#include ../ch7a-mytodo/src/bin/backend.rs:json}}
Copy

With all of that in place we can modify our handler function to push the tasks

we get back from query_task onto a response object, and then convert that to

Json on the way out:

{{#include ../ch7a-mytodo/src/bin/backend.rs:tasks_get}}
Copy

Run the backend, refresh your browser, and you should see json similar to the

sample above. (It won't be pretty-printed -- you can `curl --silent

localhost:8000/tasks/ | jq .` if you're into that.)

 REST API Layer Wrap-Up#

We just built a functional REST API backend, and I don't know about you, but I

didn't even break a sweat. Of course, there are things we'd do differently in a

production app:

* testing, of both the unit and integration varieties

* documentation, from comments to docstrings to REST API user (developer) docs

* stricter conformance to JSON API

* API versioning

* database connection pooling

  so that we don't have to do establish_connection for every request, which

  would be important under load

* make our response object use a parameterized type so that we can return

  different object types as the API grows new features

In the next chapter we will place the final layer -- a browser-based UI based on

the Seed framework. But first -- some exercises!

 REST API Layer Exercises#

These exercises are more challenging and will require consulting more external

documentation than in the last chapter.

 Bring the API in conformance with the JSON API Spec#

Specifically, this part:

 A resource object MUST contain at least the following top-level members:

 

 * id

 * type

 Exception: The id member is not required when the resource object originates at

 the client and represents a new resource to be created on the server.

 In addition, a resource object MAY contain any of these top-level members:

 * attributes: an attributes object representing some of the resource’s data.

To do this, create a new Task wrapper struct that contains the id, type, and

attributes, modify the JsonApiResponse struct to contain a vector of that

wrapper, and modify the loop around task_query to create and push this type

onto the response.

 Use Connection Pooling#

Read the Rocket documentation on [database connection

pooling](rocket.rs/v0.4/guide/state/#databa...) and implement it in

backend.rs.

(译者注：以下为多余部分，我也不知为何会多，提交的原文本来没有的）
创建 REST API 层

chen0adapter 翻译于 4 年前

0 重译