This is a guest blog post from of – a technologist from the great city of Montreal.

这是来自 （ ）的客座博客文章， 是蒙特利尔大城市的技术专家。

前言 (Foreword)

This tutorial is meant for beginners. If you get stuck along the way, try to power through and it will probably click. If there’s anything you just don’t get or want some help with, email or leave a comment below.

本教程适用于初学者。 如果您一路陷入困境，请尝试接通电源，它可能会发出咔嗒声。 如果您没有得到任何帮助或需要帮助，请发送电子邮件至或在下面发表评论。

介绍 (Intro)

Making an API can be a lot of work. Developers need to handle details like serialization, URL mapping, validation, authentication, authorization, versioning, testing, databases, custom code for models and views, etc. Services like Firebase and Parse exist to make this way easier. Using a Backend-as-a-Service, developers can focus more on building unique user experiences.

制作API可能需要很多工作。 开发人员需要处理诸如序列化，URL映射，验证，身份验证，授权，版本控制，测试，数据库，模型和视图的自定义代码等详细信息。存在诸如Firebase和Parse之类的服务来简化此方法。 使用后端即服务，开发人员可以将更多精力集中在构建独特的用户体验上。

Some drawbacks of using third party backend providers include a lack of control over the backend code, inability to self-host, no intellectual property, etc.. Having control over the code and leveraging the time-saving convenience of a BaaS would be ideal, but most REST API frameworks in the wild still require a lot of boilerplate. One popular example of this would be the awesomely heavy . Another great project which requires way less boilerplate and makes building APIs super easy is (highly recommended). We wanted to get rid of all boilerplate though, including the database queries that would normally need to be written for views.

使用第三方后端提供程序的一些缺点包括缺乏对后端代码的控制，无法自我托管，没有知识产权等。对代码进行控制并利用BaaS的省时便利将是理想的选择，但是大多数野外的REST API框架仍然需要大量样板。 一个流行的例子是令人敬畏的 。 是另一个伟大的项目，它需要更少的样板并使得构建API非常容易。 但是，我们希望摆脱所有样板，包括通常需要为视图编写的数据库查询。

Enter Ramses, a simple way to generate a powerful backend from a YAML file (actually a dialect for REST APIs called ). In this post we’ll show you how to go from zero to your own production-ready backend in a few minutes.

输入Ramses，这是一种从YAML文件（实际上是REST API的方言，称为 ）生成功能强大的后端的简单方法。 在这篇文章中，我们将向您展示如何在几分钟内从零到自己的生产就绪后端。

Want the code?

想要代码吗？

引导新产品API (Bootstrap a new product API)

先决条件 (Prerequisites)

We assume you are working inside a fresh , and are running both and with default configurations. We use to interact with the API but you can also use curl or other http clients.

我们假设您正在一个全新的 ，并且正在使用默认配置运行和 。 我们使用与API进行交互，但您也可以使用curl或其他http客户端。

If at any time you get stuck or want to see the final working version of the code for this tutorial, .

如果您有任何困难或想查看本教程代码的最终工作版本， 。

场景：一家工厂（希望）制作美味的比萨 (Scenario: a factory to make (hopefully) delicious pizzas)

We want to create an API for our new pizzeria. Our backend should know about all the different toppings, cheeses, sauces, and crusts that can be used and the different combinations of them that go into making various pizza styles.

我们想为我们的新比萨店创建一个API。 我们的后端应了解可以使用的所有不同配料，奶酪，调味料和硬皮，以及它们用于制作各种披萨风格的不同组合。

1122

The installer will ask which database backend you want to use. Pick option “1” to use SQLAlchemy.

安装程序将询问您要使用哪个数据库后端。 选择选项“ 1”以使用SQLAlchemy。

Change into the newly created directory and look around.

转到新创建的目录并四处查看。

11

All endpoints will be accessible at the URI /api/endpoint-name/item-id. The built-in server runs on port 6543 by default. Have a read through local.ini and see if it makes any sense. Then run the server to start interacting with your new backend.

所有端点都可以通过URI / api / endpoint-name / item-id访问。 内置服务器默认在端口6543上运行。 通读local.ini ，看是否有意义。 然后运行服务器以开始与您的新后端进行交互。

11

Look at api.raml to get an idea of how endpoints are specified.

查看api.raml ，以了解如何指定端点。

11223344556677889910101111121213131414151516161717181819192020212122222323242425252626272728282929

As you can see, we have a resource at /api/items which is defined by the schema in items.json.

如您所见，我们在/ api / items拥有一个资源，该资源由items.json中的模式定义。

1122334455667788991010111112121313141415151616171718181919

资料建模 (Data modeling)

模式！ (Schemas!)

Schemas describe the structure of data.

模式描述数据的结构。

We need to create them for each of the different kinds of ingredients that we will make our pizzas with. The default schema from Ramses is a basic example in items.json.

我们需要为制作披萨时使用的每种不同食材创建它们。 Ramses的默认架构是items.json中的一个基本示例。

Since we’re going to have more than one schema in our project, let’s create a new directory and move the default schema into it to keep things clean.

由于我们的项目中将有多个架构，因此我们创建一个新目录并将默认架构移入其中以保持环境整洁。

112233

Rename items.json to pizzas.json and open it in a text editor. Then copy its contents into new files in the same directory with the names toppings.json, cheeses.json, sauces.json, and crusts.json.

将items.json重命名为pizzas.json并在文本编辑器中将其打开。 然后将其内容复制到新文件与名称toppings.json，cheeses.json，sauces.json和crusts.json同一目录下。

11223344556677

In each new schema, update the value of the "title" field for the different kinds of things that are being described (e.g. "title": "Pizza schema", "title": "Topping schema" etc.).

在每个新模式中，为正在描述的不同种类的事物（例如"title": "Pizza schema" ， "title": "Topping schema"等）更新"title"字段的值。

Let’s edit the pizzas.json schema to hook up the ingredients that would go into a given style of pizza.

让我们编辑pizzas.json模式以连接将要放入给定样式的披萨的配料。

After the "description" field, add the following relations with the ingredients:

在"description"字段之后，添加以下与成分的关系：

1122334455667788991010111112121313141415151616171718181919202021212222232324242525262627272828292930303131323233333434353536363737383839394040

关系101 (Relations 101)

We need to do the same for each of the ingredients to link them to the pizza style recipes that call for them. In toppings.json and cheeses.json we need a "foreign_key" field pointing to the specific pizza style that each topping would be used for (again, put this after the "description" field):

我们需要对每种食材都做同样的事情，以将它们链接到需要它们的比萨风格食谱。 在toppings.json和cheeses.json我们需要一个"foreign_key"字段指向特定的比萨风格，每个浇头将用于（同样，把这个后"description"字段）：

11223344556677889910101111

Then in both sauces.json and crusts.json we do the reverse (by specifying "relationship" fields instead of "foreign_key" fields) because these two ingredients are being referenced by the particular instances of the pizza styles that call for them:

然后，在sauces.json和crusts.json中，我们都做相反的操作（通过指定"relationship"字段而不是"foreign_key"字段），因为这两种配料被需要它们的披萨样式的特定实例引用：

112233445566778899101011111212

For crusts.json just make sure to set the value of "backref_name" to "crust".

对于crusts.json，只需确保将"backref_name"的值设置为"crust" 。

One thing to note here is that only a crust is really required to make a pizza if you think long and hard about it. Maybe we’d have to call it bread at that point, but let’s not get too philosophical.

这里要注意的一件事是，如果您想一想很长时间，那么制作披萨实际上只需要外壳即可。 也许那时我们不得不称其为面包，但我们不要太哲学了。

Also note that we have two different “directions” of pizza-to-ingredient relationships going on. Pizzas have many toppings and cheeses. These are “One (pizza) to Many (ingredients)” relationships. Pizzas only have one sauce and one crust though. Each sauce or crust may be called for by many different pizza styles. When talking about pizzas, we say there is a “Many (pizzas) to One (sauce/crust)” relationship. Whichever “direction” you want to call it by is only a matter of the entity you are talking about as a point of reference.

还要注意，我们有两种不同的披萨与成分关系的“方向”。 比萨有很多浇头和奶酪。 这些是“一对（披萨）对许多（成分）”的关系。 比萨只有一种酱汁和一层皮。 每种调味品或外壳都可能需要许多不同的披萨样式。 在谈论披萨时，我们说有一种“披萨”与“一酱”的关系。 您想称呼哪个“方向”仅是您作为参考点所谈论的实体的问题。

One-to-Many relationships have a relationship field on the “One” side and a foreign_key field on the “Many” side, e.g. pizzas (as described in pizzas.json) have many "toppings":

一对多关系在“一个”侧具有一个relationship字段，在“许多”侧具有一个foreign_key字段，例如，比萨饼（如pizzas.json中所述 ）具有许多"toppings" ：

11223344556677889910101111

…and each topping (as described in toppings.json) is called for by certain specific pizzas ("pizza_id"):

…并且每个浇头 （如"pizza_id"所述）由某些特定的披萨（ "pizza_id" ） "pizza_id" ：

11223344556677889910101111

Many-to-One relationships have a foreign_key field on the “Many” side and a relationship field on the One side. That’s why toppings have a foreign_key field pointing to specific pizzas, and pizzas have a relationship field pointing to all their toppings.

多对一关系在“许多”侧具有一个foreign_key字段，在“一侧”具有一个relationship字段。 这就是为什么浇头具有指向特定比萨饼的foreign_key字段，而比萨饼具有指向其所有浇头的relationship字段的原因。

Backref和ondelete参数 (Backref & ondelete arguments)

To learn about using relational database concepts in detail, refer to the . Very briefly:

要了解有关使用关系数据库概念的详细信息，请参阅 。 非常简短：

A backref argument tells the database that when one model is referenced by another, the “referencing” model (which has a foreign_key field) will also provide access “backwards” to the “referenced” model.

一个backref参数告诉数据库，当一个模型被另一个模型引用时，“引用”模型（具有foreign_key字段）也将提供对“引用”模型的“向后访问”。

An ondelete argument is telling the database that when the instance of a referenced model is deleted, to change the value of the referencing field accordingly. NULLIFY means that the value will be set to null.

一个ondelete参数告诉数据库，当删除引用模型的实例时，要相应地更改引用字段的值。 NULLIFY表示该值将设置为null 。

创建端点 (Creating endpoints)

At this point, our kitchen is almost ready. In order to actually start making pizzas, we need to hook up some API endpoints to access the data models we just created.

至此，我们的厨房快要准备好了。 为了真正开始制作披萨，我们需要连接一些API端点以访问我们刚刚创建的数据模型。

Let’s edit api.raml by replacing the default “items” endpoint for each of our resources like so:

让我们通过替换每个资源的默认“ items”终结点来编辑api.raml ，如下所示：

112233445566778899101011111212131314141515161617171818191920202121222223232424252526262727282829293030313132323333343435353636373738383939404041414242434344444545464647474848494950505151525253535454555556565757585859596060616162626363646465656666676768686969707071717272737374747575767677777878797980808181828283838484858586868787888889899090919192929393949495959696979798989999100100101101102102103103104104105105106106

Notice the order of endpoint definitions. /pizzas is placed after /toppings and /cheeses because it relates to them. /sauces and /crusts are placed after /pizzas because they relate to it. If you get any kind of errors about things missing or not being defined when starting the server, check the order of definition.

注意端点定义的顺序 。 /pizzas放在/toppings和/cheeses因为它与它们有关。 /sauces和/crusts放在/pizzas后面，因为它们与之相关。 如果在启动服务器时遇到任何有关缺少或未定义的错误，请检查定义的顺序。

Now we can create our own ingredients and pizza styles!

现在，我们可以创建自己的食材和比萨饼样式！

Restart the server and get cooking.

重新启动服务器并开始烹饪。

11

Let’s start by making a Hawaiian style pizza:

让我们从制作夏威夷风格的比萨开始：

1122

1122

1122

1122

1122

11

瞧！ (Voila!)

Here it is in all its greasy glory:

这是所有油腻的荣耀：

112233445566778899101011111212131314141515161617171818191920202121222223232424252526262727282829293030313132323333343435353636373738383939

种子数据 (Seed data)

The last step for bonus points is to import a bunch of existing ingredient records to make things more fun.

奖励积分的最后一步是导入一堆现有成分记录，以使事情变得更加有趣。

First create a seeds/ directory inside the pizza_factory project and download the seed data:

首先在pizza_factory项目中创建一个seed seeds/目录，然后下载种子数据：

112233445566

Now, use the built-in post2api script to load all the ingredients into your API.

现在，使用内置的post2api脚本将所有成分加载到您的API中。

11223344

You can now list the different ingredients easily.

现在，您可以轻松列出不同的成分。

11

Or search for the ingredients by name.

或按名称搜索成分。

1122334455667788991010111112121313141415151616171718181919202021212222232324242525262627272828292930303131323233333434353536363737383839394040414142424343444445454646474748484949505051515252535354545555565657575858595960606161626263636464656566666767686869697070

So, let’s make one last pizza by finding the ingredients. How about a vegetarian one this time?

因此，让我们通过查找食材制作最后一个披萨。 这次素食主义者怎么样？

Maybe a bit of spinach, ricotta, sun-dried tomato sauce, and a whole wheat crust. First we find our IDs (yours may be different)..

也许是一些菠菜，意大利乳清干酪，晒干的番茄酱和全麦面包皮。 首先，我们找到我们的ID（您的名称可能有所不同）。

11223344556677889910101111121213131414151516161717181819192020

Bake for 0 seconds, and..

烘烤0秒钟，然后..

1122334455667788991010111112121313141415151616171718181919202021212222232324242525262627272828292930303131323233333434353536363737383839394040

翻译自: