教程3：创建简单的 REST API

在本教程中,我们将解释如何创建一个简单的应用程序,它提供了一个使用不同HTTP方法的 RESTful API:

In this tutorial, we will explain how to create a simple application that provides a RESTful API using the different HTTP methods:

  • GET去获取并搜索数据
  • POST 去添加数据
  • PUT去更新数据
  • DELETE 去删除数据
  • GET to retrieve and search data
  • POST to add data
  • PUT to update data
  • DELETE to delete data

定义 API

API包含以下的方法：

The API consists of the following methods:

MethodURLAction
GET/api/robotsRetrieves all robots
GET/api/robots/search/AstroSearches for robots with ‘Astro’ in their name
GET/api/robots/2Retrieves robots based on primary key
POST/api/robotsAdds a new robot
PUT/api/robots/2Updates robots based on primary key
DELETE/api/robots/2Deletes robots based on primary key

创建应用

因为这个应用很简单，我们不会去开发一个全栈的MVC应用，在这个例子中我们使用:doc:micro application <micro> 去满足我们的需求。

As the application is so simple, we will not implement any full MVC environment to develop it. In this case, we will use a micro application to meet our goal.

下面的文件目录结构就足够了:

The following file structure is more than enough:

  1. my-rest-api/
  2.     models/
  3.         Robots.php
  4.     index.php
  5.     .htaccess

首页我们需要.htaccess文件，包含应用需要的重新规则：

First, we need an .htaccess file that contains all the rules to rewrite the URIs to the index.php file, that is our application:

  1. <IfModule mod_rewrite.c>
  2.     RewriteEngine On
  3.     RewriteCond %{REQUEST_FILENAME} !-f
  4.     RewriteRule ^(.*)$ index.php?_url=/$1 [QSA,L]
  5. </IfModule>

然后在index.php中我们输入如下代码：

Then, in the index.php file we create the following:

  1. <?php
  3. use Phalcon\Mvc\Micro;
  5. $app = new Micro();
  7. //define the routes here
  9. $app->handle();

现在像我们上面定义的那样创建路由：

Now we will create the routes as we defined above:

  1. <?php
  3. use Phalcon\Mvc\Micro;
  5. $app = new Micro();
  7. //Retrieves all robots
  8. $app->get('/api/robots', function() {
  10. });
  12. //Searches for robots with $name in their name
  13. $app->get('/api/robots/search/{name}', function($name) {
  15. });
  17. //Retrieves robots based on primary key
  18. $app->get('/api/robots/{id:[0-9]+}', function($id) {
  20. });
  22. //Adds a new robot
  23. $app->post('/api/robots', function() {
  25. });
  27. //Updates robots based on primary key
  28. $app->put('/api/robots/{id:[0-9]+}', function() {
  30. });
  32. //Deletes robots based on primary key
  33. $app->delete('/api/robots/{id:[0-9]+}', function() {
  35. });
  37. $app->handle();

每个路由定义和HTTP方法名称相同,,我们通过路由匹配模式作为第一个参数,其次是一个处理程序。在这种情况下,处理程序是一个匿名函数。例如路由: ‘/api/robots/{id:[0-9]+}’中显式地设置“id”参数必须是一个数字格式的。

Each route is defined with a method with the same name as the HTTP method, as first parameter we pass a route pattern, followed by a handler. In this case, the handler is an anonymous function. The following route: ‘/api/robots/{id:[0-9]+}’, by example, explicitly sets that the “id” parameter must have a numeric format.

当一个定义好路由匹配请求的URI时,应用程序执行相应的处理程序。

When a defined route matches the requested URI then the application executes the corresponding handler.

创建数据模型

我们的API提供了“机器人”的信息,这些数据是存储在数据库中。下面的模型允许我们以面向对象的方式访问数据表。我们使用内置的验证器和简单的验证实现一些业务规则。这样做可以更加简单的保存数据并满足应用程序要求:

Our API provides information about ‘robots’, these data are stored in a database. The following model allows us to access that table in an object-oriented way. We have implemented some business rules using built-in validators and simple validations. Doing this will give us the peace of mind that saved data meet the requirements of our application:

  1. <?php
  3. use Phalcon\Mvc\Model;
  4. use Phalcon\Mvc\Model\Message;
  5. use Phalcon\Mvc\Model\Validator\Uniqueness;
  6. use Phalcon\Mvc\Model\Validator\InclusionIn;
  8. class Robots extends Model
  9. {
  11.     public function validation()
  12.     {
  13.         //Type must be: droid, mechanical or virtual
  14.         $this->validate(new InclusionIn(
  15.             array(
  16.                 "field"  => "type",
  17.                 "domain" => array("droid", "mechanical", "virtual")
  18.             )
  19.         ));
  21.         //Robot name must be unique
  22.         $this->validate(new Uniqueness(
  23.             array(
  24.                 "field"   => "name",
  25.                 "message" => "The robot name must be unique"
  26.             )
  27.         ));
  29.         //Year cannot be less than zero
  30.         if ($this->year < 0) {
  31.             $this->appendMessage(new Message("The year cannot be less than zero"));
  32.         }
  34.         //Check if any messages have been produced
  35.         if ($this->validationHasFailed() == true) {
  36.             return false;
  37.         }
  38.     }
  40. }

现在,我们必须建立一个应用程序中数据模型使用的连接，并加载好它:

Now, we must set up a connection to be used by this model and load it within our app:

  1. <?php
  3. use Phalcon\Loader;
  4. use Phalcon\Mvc\Micro;
  5. use Phalcon\DI\FactoryDefault;
  6. use Phalcon\Db\Adapter\Pdo\Mysql as PdoMysql;
  8. // Use Loader() to autoload our model
  9. $loader = new Loader();
  11. $loader->registerDirs(array(
  12.     __DIR__ . '/models/'
  13. ))->register();
  15. $di = new FactoryDefault();
  17. //Set up the database service
  18. $di->set('db', function(){
  19.     return new PdoMysql(array(
  20.         "host"      => "localhost",
  21.         "username"  => "asimov",
  22.         "password"  => "zeroth",
  23.         "dbname"    => "robotics"
  24.     ));
  25. });
  27. //Create and bind the DI to the application
  28. $app = new Micro($di);

获取数据

第一个“处理程序”,实现返回所有可用的机器人的方法。让我们用PHQL执行这个简单的查询返回JSON格式的结果:

The first “handler” that we will implement is which by method GET returns all available robots. Let’s use PHQL to perform this simple query returning the results as JSON:

  1. <?php
  3. //Retrieves all robots
  4. $app->get('/api/robots', function() use ($app) {
  6.     $phql = "SELECT * FROM Robots ORDER BY name";
  7.     $robots = $app->modelsManager->executeQuery($phql);
  9.     $data = array();
  10.     foreach ($robots as $robot) {
  11.         $data[] = array(
  12.             'id'    => $robot->id,
  13.             'name'  => $robot->name,
  14.         );
  15.     }
  17.     echo json_encode($data);
  18. });

PHQL 让我们使用高级的、面向对象的SQL语言编写查询，程序内部取决于我们正在使用的数据库系统转换成正确的SQL语句。下面代码匿名函数中的“use”允许我们将一些变量从全球传到局部作用域。

PHQL, allow us to write queries using a high-level, object-oriented SQL dialect that internally translates to the right SQL statements depending on the database system we are using. The clause “use” in the anonymous function allows us to pass some variables from the global to local scope easily.

按名称搜索的处理程序代码如下所示:

The searching by name handler would look like:

  1. <?php
  3. //Searches for robots with $name in their name
  4. $app->get('/api/robots/search/{name}', function($name) use ($app) {
  6.     $phql = "SELECT * FROM Robots WHERE name LIKE :name: ORDER BY name";
  7.     $robots = $app->modelsManager->executeQuery($phql, array(
  8.         'name' => '%' . $name . '%'
  9.     ));
  11.     $data = array();
  12.     foreach ($robots as $robot) {
  13.         $data[] = array(
  14.             'id'    => $robot->id,
  15.             'name'  => $robot->name,
  16.         );
  17.     }
  19.     echo json_encode($data);
  21. });

按字段“id”搜索很相似,在这种情况下,我们也返回结果是否找到相关机器人:

Searching by the field “id” it’s quite similar, in this case, we’re also notifying if the robot was found or not:

  1. <?php
  3. use Phalcon\Http\Response;
  5. //Retrieves robots based on primary key
  6. $app->get('/api/robots/{id:[0-9]+}', function($id) use ($app) {
  8.     $phql = "SELECT * FROM Robots WHERE id = :id:";
  9.     $robot = $app->modelsManager->executeQuery($phql, array(
  10.         'id' => $id
  11.     ))->getFirst();
  13.     //Create a response
  14.     $response = new Response();
  16.     if ($robot == false) {
  17.         $response->setJsonContent(array('status' => 'NOT-FOUND'));
  18.     } else {
  19.         $response->setJsonContent(array(
  20.             'status' => 'FOUND',
  21.             'data'   => array(
  22.                 'id'   => $robot->id,
  23.                 'name' => $robot->name
  24.             )
  25.         ));
  26.     }
  28.     return $response;
  29. });

插入数据

将请求中的数据作为JSON串,我们使用PHQL插入数据:

Taking the data as a JSON string inserted in the body of the request, we also use PHQL for insertion:

  1. <?php
  3. use Phalcon\Http\Response;
  5. //Adds a new robot
  6. $app->post('/api/robots', function() use ($app) {
  8.     $robot = $app->request->getJsonRawBody();
  10.     $phql = "INSERT INTO Robots (name, type, year) VALUES (:name:, :type:, :year:)";
  12.     $status = $app->modelsManager->executeQuery($phql, array(
  13.         'name' => $robot->name,
  14.         'type' => $robot->type,
  15.         'year' => $robot->year
  16.     ));
  18.     //Create a response
  19.     $response = new Response();
  21.     //Check if the insertion was successful
  22.     if ($status->success() == true) {
  24.         //Change the HTTP status
  25.         $response->setStatusCode(201, "Created");
  27.         $robot->id = $status->getModel()->id;
  29.         $response->setJsonContent(array('status' => 'OK', 'data' => $robot));
  31.     } else {
  33.         //Change the HTTP status
  34.         $response->setStatusCode(409, "Conflict");
  36.         //Send errors to the client
  37.         $errors = array();
  38.         foreach ($status->getMessages() as $message) {
  39.             $errors[] = $message->getMessage();
  40.         }
  42.         $response->setJsonContent(array('status' => 'ERROR', 'messages' => $errors));
  43.     }
  45.     return $response;
  46. });

更新数据

数据更新和插入类似，id被传递过去指明哪个机器人必须被更新。

The data update is similar to insertion. The “id” passed as parameter indicates what robot must be updated:

  1. <?php
  3. use Phalcon\Http\Response;
  5. //Updates robots based on primary key
  6. $app->put('/api/robots/{id:[0-9]+}', function($id) use($app) {
  8.     $robot = $app->request->getJsonRawBody();
  10.     $phql = "UPDATE Robots SET name = :name:, type = :type:, year = :year: WHERE id = :id:";
  11.     $status = $app->modelsManager->executeQuery($phql, array(
  12.         'id' => $id,
  13.         'name' => $robot->name,
  14.         'type' => $robot->type,
  15.         'year' => $robot->year
  16.     ));
  18.     //Create a response
  19.     $response = new Response();
  21.     //Check if the insertion was successful
  22.     if ($status->success() == true) {
  23.         $response->setJsonContent(array('status' => 'OK'));
  24.     } else {
  26.         //Change the HTTP status
  27.         $response->setStatusCode(409, "Conflict");
  29.         $errors = array();
  30.         foreach ($status->getMessages() as $message) {
  31.             $errors[] = $message->getMessage();
  32.         }
  34.         $response->setJsonContent(array('status' => 'ERROR', 'messages' => $errors));
  35.     }
  37.     return $response;
  38. });

删除数据

数据删除与更新相近。“id”作为参数传递过去指明哪个机器人必须被删除:

The data delete is similar to update. The “id” passed as parameter indicates what robot must be deleted:

  1. <?php
  3. use Phalcon\Http\Response;
  5. //Deletes robots based on primary key
  6. $app->delete('/api/robots/{id:[0-9]+}', function($id) use ($app) {
  8.     $phql = "DELETE FROM Robots WHERE id = :id:";
  9.     $status = $app->modelsManager->executeQuery($phql, array(
  10.         'id' => $id
  11.     ));
  13.     //Create a response
  14.     $response = new Response();
  16.     if ($status->success() == true) {
  17.         $response->setJsonContent(array('status' => 'OK'));
  18.     } else {
  20.         //Change the HTTP status
  21.         $response->setStatusCode(409, "Conflict");
  23.         $errors = array();
  24.         foreach ($status->getMessages() as $message) {
  25.             $errors[] = $message->getMessage();
  26.         }
  28.         $response->setJsonContent(array('status' => 'ERROR', 'messages' => $errors));
  30.     }
  32.     return $response;
  33. });

测试应用

使用curl_ 测试我们的路由是否正常工作：

Using curl we’ll test every route in our application verifying its proper operation:

获得所有机器人：

Obtain all the robots:

  1. curl -i -X GET http://localhost/my-rest-api/api/robots
  3. HTTP/1.1 200 OK
  4. Date: Wed, 12 Sep 2012 07:05:13 GMT
  5. Server: Apache/2.2.22 (Unix) DAV/2
  6. Content-Length: 117
  7. Content-Type: text/html; charset=UTF-8
  9. [{"id":"1","name":"Robotina"},{"id":"2","name":"Astro Boy"},{"id":"3","name":"Terminator"}]

通过名字搜索机器人：

Search a robot by its name:

  1. curl -i -X GET http://localhost/my-rest-api/api/robots/search/Astro
  3. HTTP/1.1 200 OK
  4. Date: Wed, 12 Sep 2012 07:09:23 GMT
  5. Server: Apache/2.2.22 (Unix) DAV/2
  6. Content-Length: 31
  7. Content-Type: text/html; charset=UTF-8
  9. [{"id":"2","name":"Astro Boy"}]

通过id获得机器人：

Obtain a robot by its id:

  1. curl -i -X GET http://localhost/my-rest-api/api/robots/3
  3. HTTP/1.1 200 OK
  4. Date: Wed, 12 Sep 2012 07:12:18 GMT
  5. Server: Apache/2.2.22 (Unix) DAV/2
  6. Content-Length: 56
  7. Content-Type: text/html; charset=UTF-8
  9. {"status":"FOUND","data":{"id":"3","name":"Terminator"}}

插入一个新机器人：

Insert a new robot:

  1. curl -i -X POST -d '{"name":"C-3PO","type":"droid","year":1977}'
  2.     http://localhost/my-rest-api/api/robots
  4. HTTP/1.1 201 Created
  5. Date: Wed, 12 Sep 2012 07:15:09 GMT
  6. Server: Apache/2.2.22 (Unix) DAV/2
  7. Content-Length: 75
  8. Content-Type: text/html; charset=UTF-8
  10. {"status":"OK","data":{"name":"C-3PO","type":"droid","year":1977,"id":"4"}}

插入一个名称存在的机器人：

Try to insert a new robot with the name of an existing robot:

  1. curl -i -X POST -d '{"name":"C-3PO","type":"droid","year":1977}'
  2.     http://localhost/my-rest-api/api/robots
  4. HTTP/1.1 409 Conflict
  5. Date: Wed, 12 Sep 2012 07:18:28 GMT
  6. Server: Apache/2.2.22 (Unix) DAV/2
  7. Content-Length: 63
  8. Content-Type: text/html; charset=UTF-8
  10. {"status":"ERROR","messages":["The robot name must be unique"]}

或者更新一个类型未知的机器人：

Or update a robot with an unknown type:

  1. curl -i -X PUT -d '{"name":"ASIMO","type":"humanoid","year":2000}'
  2.     http://localhost/my-rest-api/api/robots/4
  4. HTTP/1.1 409 Conflict
  5. Date: Wed, 12 Sep 2012 08:48:01 GMT
  6. Server: Apache/2.2.22 (Unix) DAV/2
  7. Content-Length: 104
  8. Content-Type: text/html; charset=UTF-8
  10. {"status":"ERROR","messages":["Value of field 'type' must be part of
  11.     list: droid, mechanical, virtual"]}

最后删除一个机器人：

Finally, delete a robot:

  1. curl -i -X DELETE http://localhost/my-rest-api/api/robots/4
  3. HTTP/1.1 200 OK
  4. Date: Wed, 12 Sep 2012 08:49:29 GMT
  5. Server: Apache/2.2.22 (Unix) DAV/2
  6. Content-Length: 15
  7. Content-Type: text/html; charset=UTF-8
  9. {"status":"OK"}

结论

就像我们上面看到的一样使用phalcon创建一个RESTful API非常的简单。接下来我们会讲解到如何使用微应用和:doc:`PHQL <phql>`语言。

As we have seen, develop a RESTful API with Phalcon is easy. Later in the documentation we’ll explain in detail how to use micro applications and the PHQL language.